@jossuealcala/madre 0.4.0 → 0.4.1

package/public/troubleshooting.js

@@ -46,8 +46,39 @@ const loginAgent = {
 const same = (commands) => ({ darwin: commands, linux: commands });
 
 export const CONDITIONS = [
+  {
+    id: 'claude-api-key-shadows-plan',
+    code: 'MU-001',
+    agent: 'claude',
+    severity: 'common',
+    title: 'ANTHROPIC_API_KEY takes precedence over the claude.ai plan',
+    match: /connectors are disabled because ANTHROPIC_API_KEY|another auth source is set and takes precedence|takes precedence over your claude\.ai login/i,
+    diagnosis: 'Claude Code found an API key in the environment as well as the claude.ai login, and the key wins. MADRE hands the CLI the environment exactly as this machine has it, so whatever is exported in your shell profile reaches it. The turn is billed to the API account, not to the plan, and your organisation connectors do not load.',
+    remedy: 'Decide which one you mean. To work on the plan, unset the key where your shell exports it and open the room again; to work on the API, this message is only a notice and can be ignored.',
+    fixes: {
+      darwin: ['grep -rn ANTHROPIC_API_KEY ~/.zshrc ~/.zprofile ~/.zshenv 2>/dev/null', '# remove or comment the line it finds, then:', 'unset ANTHROPIC_API_KEY', '# and start MADRE from a new terminal'],
+      linux: ['grep -rn ANTHROPIC_API_KEY ~/.bashrc ~/.profile ~/.bash_profile 2>/dev/null', 'unset ANTHROPIC_API_KEY', '# and start MADRE from a new terminal'],
+    },
+  },
+  {
+    id: 'codex-reading-stdin',
+    code: 'MU-002',
+    solvedIn: 'connections',
+    agent: 'codex',
+    severity: 'informational',
+    title: 'Codex says it is reading additional input from stdin',
+    match: /Reading additional input from stdin/i,
+    diagnosis: 'A notice Codex prints, not a failure. MADRE runs it with stdin closed, so the line is harmless and the turn is decided by what Codex returned. If the turn failed, the reason is the line above this one — the exit code, or a clean exit with no answer.',
+    remedy: 'Nothing to do about the notice itself. If turns keep failing, check that this Codex is recent enough for the flags MADRE passes: `codex --version`, then update it.',
+    fixes: {
+      darwin: ['codex --version', 'npm install -g @openai/codex'],
+      linux: ['codex --version', 'npm install -g @openai/codex'],
+    },
+  },
   {
     id: 'gemini-ineligible-tier',
+    code: 'MU-003',
+    solvedIn: 'connections',
     agent: 'gemini',
     severity: 'blocking',
     title: 'Gemini refuses the personal Google login',
@@ -61,6 +92,8 @@ export const CONDITIONS = [
   },
   {
     id: 'gemini-credits-depleted',
+    code: 'MU-004',
+    solvedIn: 'connections',
     agent: 'gemini',
     severity: 'blocking',
     title: 'Gemini key out of prepaid credits',
@@ -71,6 +104,8 @@ export const CONDITIONS = [
   },
   {
     id: 'gemini-rate-limited',
+    code: 'MU-005',
+    solvedIn: 'connections',
     agent: 'gemini',
     severity: 'transient',
     title: 'Gemini key rate-limited by Google (HTTP 429)',
@@ -84,6 +119,7 @@ export const CONDITIONS = [
   },
   {
     id: 'gemini-high-demand',
+    code: 'MU-006',
     agent: 'gemini',
     severity: 'transient',
     title: 'Gemini model under high demand (503)',
@@ -94,6 +130,8 @@ export const CONDITIONS = [
   },
   {
     id: 'opencode-default-provider',
+    code: 'MU-007',
+    solvedIn: 'connections',
     agent: 'opencode',
     severity: 'blocking',
     title: 'OpenCode picked a provider without a valid session',
@@ -107,6 +145,8 @@ export const CONDITIONS = [
   },
   {
     id: 'not-signed-in',
+    code: 'MU-008',
+    solvedIn: 'connections',
     severity: 'blocking',
     title: 'Agent installed but signed out',
     match: /not logged in|sign in required|Error authenticating|unauthorized|please (?:log|sign) ?in|no credentials/i,
@@ -117,6 +157,7 @@ export const CONDITIONS = [
   },
   {
     id: 'not-installed',
+    code: 'MU-009',
     severity: 'blocking',
     title: 'Agent not found on this computer',
     match: /is not installed on this computer|not found on this computer|ENOENT.*(codex|claude|gemini|opencode)/i,
@@ -127,6 +168,7 @@ export const CONDITIONS = [
   },
   {
     id: 'adapter-pending',
+    code: 'MU-010',
     severity: 'blocking',
     title: 'Agent detected, adapter not enabled',
     match: /adapter is not enabled yet|does not have a supported MADRE adapter/i,
@@ -136,6 +178,7 @@ export const CONDITIONS = [
   },
   {
     id: 'claude-args',
+    code: 'MU-011',
     agent: 'claude',
     severity: 'fixed',
     title: 'Claude read the prompt as an MCP config path',
@@ -146,6 +189,7 @@ export const CONDITIONS = [
   },
   {
     id: 'timeout',
+    code: 'MU-012',
     severity: 'tunable',
     title: 'Agent did not respond before the timeout',
     match: /did not respond before the timeout|went silent for/i,
@@ -158,6 +202,7 @@ export const CONDITIONS = [
   },
   {
     id: 'interrupted',
+    code: 'MU-013',
     severity: 'informational',
     title: 'Turn interrupted by a MADRE restart',
     match: /interrupted because MADRE is shutting down|MADRE stopped while|turn was not completed/i,
@@ -167,6 +212,7 @@ export const CONDITIONS = [
   },
   {
     id: 'message-too-long',
+    code: 'MU-014',
     severity: 'tunable',
     title: 'Message rejected for length',
     match: /Message is too long/i,
@@ -179,6 +225,7 @@ export const CONDITIONS = [
   },
   {
     id: 'limits-real',
+    code: 'MU-015',
     severity: 'informational',
     title: 'Where the rings get their numbers',
     match: /ring|quota|limit window|resets|rollout|oauth usage|window reset|limits-real/i,
@@ -188,6 +235,7 @@ export const CONDITIONS = [
   },
   {
     id: 'budget-exhausted',
+    code: 'MU-016',
     severity: 'tunable',
     title: 'Local token budget exhausted for an agent',
     match: /MADRE exhausted|local room token budget/i,
@@ -200,6 +248,7 @@ export const CONDITIONS = [
   },
   {
     id: 'port-in-use',
+    code: 'MU-017',
     severity: 'blocking',
     title: 'Port already in use',
     match: /EADDRINUSE|already in use/i,
@@ -212,6 +261,7 @@ export const CONDITIONS = [
   },
   {
     id: 'stream-reconnecting',
+    code: 'MU-018',
     severity: 'blocking',
     title: 'Live stream keeps reconnecting',
     match: /reconnecting|EventSource|ECONNREFUSED/i,
@@ -221,6 +271,7 @@ export const CONDITIONS = [
   },
   {
     id: 'opencode-server-error',
+    code: 'MU-019',
     agent: 'opencode',
     severity: 'transient',
     title: 'OpenCode reported an unexpected server error',
@@ -231,6 +282,7 @@ export const CONDITIONS = [
   },
   {
     id: 'runaway-room',
+    code: 'MU-020',
     severity: 'blocking',
     title: 'Too many agents working at once',
     match: /agents are working at once|already answering another turn|no second plan will start|has been running for/i,
@@ -241,6 +293,7 @@ export const CONDITIONS = [
   // ---- capability assistance: how an agent could gain a scope it lacks ----
   {
     id: 'scope-gemini-imageGen',
+    code: 'MU-051',
     agent: 'gemini',
     severity: 'informational',
     title: 'Gemini: generating images',
@@ -251,6 +304,7 @@ export const CONDITIONS = [
   },
   {
     id: 'scope-claude-imageGen',
+    code: 'MU-052',
     agent: 'claude',
     severity: 'informational',
     title: 'Claude Code: generating images',
@@ -261,6 +315,7 @@ export const CONDITIONS = [
   },
   {
     id: 'scope-opencode-imageGen',
+    code: 'MU-053',
     agent: 'opencode',
     severity: 'informational',
     title: 'OpenCode: generating images',
@@ -271,6 +326,7 @@ export const CONDITIONS = [
   },
   {
     id: 'scope-web',
+    code: 'MU-021',
     severity: 'informational',
     title: 'Web access for an agent',
     match: /scope-[a-z]+-web/,
@@ -280,6 +336,7 @@ export const CONDITIONS = [
   },
   {
     id: 'slash-commands',
+    code: 'MU-022',
     severity: 'informational',
     title: 'Commands and mentions in the field box',
     match: /slash|command|\/git|\/ahp|mention|@agent/i,
@@ -289,6 +346,7 @@ export const CONDITIONS = [
   },
   {
     id: 'modes',
+    code: 'MU-023',
     severity: 'informational',
     title: 'Permission modes: #0 GHOST · #1 EXCHANGE · #2 CREATE · #3 CONTROL · #4 AIRLOCK',
     match: /mode|ghost|exchange|control|airlock|deploy|despleg|producci|override|designation|max mode|#[0-4]\b/i,
@@ -298,6 +356,7 @@ export const CONDITIONS = [
   },
   {
     id: 'lease-missing',
+    code: 'MU-024',
     severity: 'informational',
     title: 'Creating files: who grants the permission',
     match: /no CREATE lease|lease-missing|read-only and do not modify|permiso de escritura|solo lectura/i,
@@ -307,6 +366,7 @@ export const CONDITIONS = [
   },
   {
     id: 'scope-write',
+    code: 'MU-025',
     severity: 'informational',
     title: 'Creating files with an agent',
     match: /scope-[a-z]+-write/,
@@ -316,6 +376,7 @@ export const CONDITIONS = [
   },
   {
     id: 'node-version',
+    code: 'MU-026',
     severity: 'blocking',
     title: 'Node.js too old',
     match: /SyntaxError: Unexpected token|ERR_REQUIRE_ESM|engines|Unsupported engine/i,
@@ -328,6 +389,7 @@ export const CONDITIONS = [
   },
   {
     id: 'memory-unavailable',
+    code: 'MU-027',
     severity: 'degraded',
     title: 'Room memory unavailable: turns get only the recent window',
     match: /memory unavailable|memory index failed|memory recall failed|node:sqlite|SQLITE_|database disk image is malformed|memory\.sqlite/i,
@@ -340,6 +402,7 @@ export const CONDITIONS = [
   },
   {
     id: 'memory-recall',
+    code: 'MU-028',
     severity: 'informational',
     title: 'Room memory: what an agent remembers and how',
     match: /\brecall\b|recuerd|\bremember\b|memoria de la sala|<memory>|<memories>/i,
@@ -349,6 +412,7 @@ export const CONDITIONS = [
   },
   {
     id: 'memory-distill',
+    code: 'MU-029',
     severity: 'degraded',
     title: 'Distilled memories: the archivist did not run, or failed',
     match: /could not distil|distill|destil|batch skipped|archivist|memory\.distilled|memories? (were|was) not/i,
@@ -358,6 +422,8 @@ export const CONDITIONS = [
   },
   {
     id: 'memory-embeddings',
+    code: 'MU-030',
+    solvedIn: 'connections',
     severity: 'degraded',
     title: 'Embeddings paused: recall is lexical only',
     match: /embeddings paused|embedding timed out|Gemini embeddings HTTP|batchEmbedContents|LINKS NEED EMBEDDINGS/i,
@@ -370,6 +436,8 @@ export const CONDITIONS = [
   },
   {
     id: 'memory-tools',
+    code: 'MU-031',
+    solvedIn: 'connections',
     severity: 'degraded',
     title: 'An agent says it cannot search the memory (pulse-memory MCP)',
     match: /pulse-memory|memory_search|memory_recall|memory_notes|memory_timeline|memory_note|mcp.*(failed|error|not found|unavailable)|MCP server/i,
@@ -382,6 +450,7 @@ export const CONDITIONS = [
   },
   {
     id: 'memory-note',
+    code: 'MU-032',
     severity: 'informational',
     title: 'Saving a memory on request; GHOST refuses',
     match: /save (a |the |this )?memory|guarda.*memoria|memory saved|off the record.*nothing can be saved|remember this|memory_note/i,
@@ -391,6 +460,7 @@ export const CONDITIONS = [
   },
   {
     id: 'nostromo-access',
+    code: 'MU-033',
     severity: 'informational',
     title: 'NOSTROMO: boarding, reading and forgetting',
     match: /nostromo|designation|UNABLE TO COMPUTE|ARCHIVE IS SEALED|forget this memory/i,
@@ -400,6 +470,7 @@ export const CONDITIONS = [
   },
   {
     id: 'ripley',
+    code: 'MU-034',
     severity: 'informational',
     title: 'RIPLEY: rendering HTML, SVG and Markdown in the viewer',
     match: /ripley|RIPLEY is off|renders \.html|render(ed|ing)? (the )?(html|svg|markdown)/i,
@@ -409,6 +480,7 @@ export const CONDITIONS = [
   },
   {
     id: 'ollama',
+    code: 'MU-035',
     severity: 'informational',
     title: 'Ollama: local embeddings and a local archivist',
     match: /ollama|11434|local model|nomic-embed|qwen|llama3/i,
@@ -421,6 +493,7 @@ export const CONDITIONS = [
   },
   {
     id: 'madre-agent',
+    code: 'MU-036',
     severity: 'informational',
     title: '@madre: the room\'s own memory, as an agent',
     match: /@madre|madre-local|needs Ollama running with a chat model/i,
@@ -430,6 +503,7 @@ export const CONDITIONS = [
   },
   {
     id: 'install-needs-admin',
+    code: 'MU-037',
     severity: 'informational',
     title: 'Installing a CLI: npm cannot write to the system folder',
     match: /EACCES|EPERM|permission denied|Missing write access|npm ERR!.*sudo|administrator/i,
@@ -442,6 +516,7 @@ export const CONDITIONS = [
   },
   {
     id: 'privacy-leak',
+    code: 'MU-038',
     severity: 'warning',
     title: 'Privacy: an agent brought its own configuration into the room',
     match: /privacy\.redacted|privacy\.purged|private terms?|\[ENTIDAD-ORG\]|organi[sz]ation(al)? instructions|leak(ed)? (a|the) (name|company|domain)/i,
@@ -451,6 +526,7 @@ export const CONDITIONS = [
   },
   {
     id: 'control-changes',
+    code: 'MU-039',
     severity: 'informational',
     title: 'CONTROL: what changed, what was reverted, UNDO',
     match: /control\.changed|forbidden zones?|reverted|UNDO|checkpoint|changed \d+ file/i,
@@ -460,6 +536,7 @@ export const CONDITIONS = [
   },
   {
     id: 'conversations',
+    code: 'MU-040',
     severity: 'informational',
     title: 'Conversations: many per project, one memory, one at a time',
     match: /conversation|already open for this project|ROOM_IN_USE|a turn is running in this conversation|new conversation|chats\.json/i,
@@ -469,6 +546,7 @@ export const CONDITIONS = [
   },
   {
     id: 'memory-aberrations',
+    code: 'MU-041',
     severity: 'informational',
     title: 'Aberrations: what the room established is false',
     match: /aberration|aberraci|eyecat|contradict|refut|false claim|hallucinat|alucina/i,
@@ -478,6 +556,7 @@ export const CONDITIONS = [
   },
   {
     id: 'memory-cascade',
+    code: 'MU-042',
     severity: 'informational',
     title: 'Memory used · N by association',
     match: /by association|cascade|spreading activation|keeps arriving with|memory used/i,
@@ -487,6 +566,7 @@ export const CONDITIONS = [
   },
   {
     id: 'memory-cold',
+    code: 'MU-043',
     severity: 'informational',
     title: 'Cold memories: what the archive has had its chances with',
     match: /cold memor|cold zone|never once carried|had its chances/i,
@@ -496,6 +576,7 @@ export const CONDITIONS = [
   },
   {
     id: 'maturity-tests',
+    code: 'MU-044',
     severity: 'informational',
     title: 'The three tests: whether the archive works',
     match: /three tests|coverage|consistency|held-out|match test|maturity|madurez|ready to be worked in/i,
@@ -505,6 +586,7 @@ export const CONDITIONS = [
   },
   {
     id: 'module-update',
+    code: 'MU-045',
     severity: 'common',
     title: 'Updating what a module drives',
     match: /EACCES|permission denied.*npm|npm ERR!.*EACCES|update to \d|newest is|brew upgrade|install -g @playwright/i,
@@ -517,6 +599,7 @@ export const CONDITIONS = [
   },
   {
     id: 'module-add',
+    code: 'MU-046',
     severity: 'common',
     title: 'Installing a module somebody else wrote',
     match: /already taken|must live under \/api\/x\/|not a module|default export must be a module|module file|\.module\.mjs|add a module/i,
@@ -526,6 +609,7 @@ export const CONDITIONS = [
   },
   {
     id: 'local-ready',
+    code: 'MU-047',
     severity: 'common',
     title: 'Is the local model ready to be worked in?',
     match: /is .*(local|madre).*(ready|good|any good)|ready to be worked in|measured against this (room|project)|check it against this room|local\.present|not measured/i,
@@ -539,6 +623,7 @@ export const CONDITIONS = [
   },
   {
     id: 'code000',
+    code: 'MU-048',
     severity: 'blocking',
     title: 'CODE000: the archive is sealed',
     match: /CODE000|THE ARCHIVE IS SEALED|UNABLE TO COMPUTE\. UNABLE TO CLARIFY|designation|intruder/i,
@@ -548,6 +633,7 @@ export const CONDITIONS = [
   },
   {
     id: 'core-console',
+    code: 'MU-049',
     severity: 'common',
     title: 'The core closed while I was typing in it',
     match: /unable to compute|interface closed|core clos|three strikes|inquiry|order 937|mu\/th\/ur 6000/i,
@@ -557,6 +643,7 @@ export const CONDITIONS = [
   },
   {
     id: 'outbound',
+    code: 'MU-050',
     severity: 'common',
     title: 'What leaves this computer, and how to stop each thing that does',
     match: /what left this machine|outbound|leaves? (this )?(computer|machine)|sends? (my )?(code|data)|telemetry|phone home|privacy/i,

package/src/adapters/process.mjs

@@ -25,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,
@@ -52,12 +82,23 @@ export function runReadonlyProcess({
       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, {
-      cwd,
-      env,
-      stdio: ['ignore', 'pipe', 'pipe'],
-      detached: process.platform !== 'win32',
-    });
+    // 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;
+    }
     let stdout = '';
     let stderr = '';
     let settled = false;
@@ -128,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/mcp/image-server.mjs

@@ -9,12 +9,13 @@
 // Environment:
 //   PULSE_IMAGE_OUT_DIR   required, absolute lease directory
 //   PULSE_IMAGE_MODEL     default gemini-2.5-flash-image
-//   GEMINI_API_KEY        optional; otherwise the macOS keychain entry the
+//   GEMINI_API_KEY        optional; otherwise ~/.gemini/.env, then the macOS keychain entry the
 //                         Gemini CLI stores (service gemini-cli-api-key)
 //   PULSE_IMAGE_FAKE=1    write a 1×1 PNG without calling Google (tests)
 
 import { execFile } from 'node:child_process';
-import { mkdir, writeFile, realpath } from 'node:fs/promises';
+import { mkdir, readFile, writeFile, realpath } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { basename, extname, join, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
 import { OutboundLog } from '../outbound.mjs';
@@ -25,9 +26,30 @@ const SERVER_VERSION = '0.1.0';
 const DEFAULT_MODEL = 'gemini-2.5-flash-image';
 const FAKE_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==', 'base64');
 
+// Where a Gemini key can be, in the order the room should trust them: what this process was
+// given, then the file the CLI reads on every run — which is also the file MADRE itself writes
+// when a key is pasted into CONNECTIONS — and last the macOS keychain, which only exists when
+// the CLI's own sign-in put it there. Leaving the file out meant MADRE saved a key in a place it
+// then refused to look, and on Linux, where there is no keychain, that was the only place it
+// could have been: Image Studio could never find a key there at all.
+async function keyFromGeminiEnvFile(env) {
+  const home = env.GEMINI_CLI_HOME ?? homedir();
+  let text;
+  try { text = await readFile(join(home, '.gemini', '.env'), 'utf8'); } catch { return null; }
+  for (const line of text.split('\n')) {
+    const match = line.match(/^\s*(?:export\s+)?(GEMINI_API_KEY|GOOGLE_API_KEY)\s*=\s*(.*)$/);
+    if (!match) continue;
+    const value = match[2].trim().replace(/^(['"])(.*)\1$/, '$2').trim();
+    if (value) return value;
+  }
+  return null;
+}
+
 export async function resolveGeminiKey(env = process.env) {
   if (env.GEMINI_API_KEY) return env.GEMINI_API_KEY;
   if (env.GOOGLE_API_KEY) return env.GOOGLE_API_KEY;
+  const fromFile = await keyFromGeminiEnvFile(env);
+  if (fromFile) return fromFile;
   if (process.platform !== 'darwin') return null;
   // The keychain occasionally answers empty under concurrent reads; one retry.
   for (let attempt = 0; attempt < 2; attempt += 1) {

package/src/modules/image-studio.mjs

@@ -13,8 +13,9 @@ export default defineModule({
   vendor: 'MADRE · Gemini API',
   version: '1.0.0',
   summary: 'Gives Gemini CLI, Claude Code and OpenCode an image tool, through a MADRE-owned MCP server on the Gemini image models and your own key and credits.',
-  creates: ['nothing in the project \u00b7 images land in the lease folder', 'an entry in ~/.pulse/config.json', 'an MCP server per turn, started and stopped by the room', 'attached only inside a creation lease with the image scope on'],
-  requires: ['a Gemini API key with credits (the one the Gemini CLI stores, or GEMINI_API_KEY)'],
+  creates: ['nothing in the project \u00b7 images land in the lease folder', 'an entry in ~/.pulse/config.json', 'an MCP server per turn, started and stopped by the room'],
+  // Not something it writes: a condition for it to attach at all, which is what REQUIRES is for.
+  requires: ['a Gemini API key with credits (the one the Gemini CLI stores, or GEMINI_API_KEY)', 'attached only inside a creation lease with the image scope on'],
   models: MODELS,
   settings: { enabled: false, model: MODELS[0] },
   card: 'image-studio',

package/src/modules/playwright.mjs

@@ -29,7 +29,10 @@ export function playwrightServerFor({ port, outputDir, browser = 'chromium', hea
   return {
     name: PLAYWRIGHT_SERVER_NAME,
     command: 'npx',
-    args: ['--no', '@playwright/mcp', ...(headless ? ['--headless'] : []), '--isolated', '--browser', browser, '--allowed-origins', `http://127.0.0.1:${port};http://localhost:${port}`, '--blocked-origins', '*', '--output-dir', outputDir, '--no-sandbox'],
+    // `--` or npm eats them: without the separator npm takes --headless, --isolated and the
+    // rest as its own config, hands the server only their bare values, and the server exits with
+    // "too many arguments" before it speaks a word of MCP. The agent sees CONNECTION_CLOSED.
+    args: ['--no', '@playwright/mcp', '--', ...(headless ? ['--headless'] : []), '--isolated', '--browser', browser, '--allowed-origins', `http://127.0.0.1:${port};http://localhost:${port}`, '--blocked-origins', '*', '--output-dir', outputDir, '--no-sandbox'],
     env: {},
     tools: PLAYWRIGHT_TOOLS,
     brief: `a headless browser that reaches only this MADRE at http://127.0.0.1:${port}. Open a project file rendered by RIPLEY at http://127.0.0.1:${port}/preview/project/<path>, click, read the console and network, take screenshots (they land in ${outputDir}). Nothing else on the network is reachable through it.`,
@@ -56,7 +59,7 @@ export default defineModule({
       runs: [{ name: PLAYWRIGHT_PACKAGE, version }],
       settings: { browser: ctx.settings.browser ?? 'chromium', headless: ctx.settings.headless !== false },
       status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? (version ? `${t('on')} · ${ctx.settings.browser}` : t('on · the browser server is not installed')) : version ? t('off') : t('off · the browser server is not installed') },
-      preflight: version ? { ok: true, problems: [] } : { ok: false, problems: ['Install the browser server first: npm install -g @playwright/mcp && npx playwright install chromium'] },
+      preflight: version ? { ok: true, problems: [] } : { ok: false, problems: ['Install the browser server first: npm install -g @playwright/mcp, then its browser: npx @playwright/mcp install-browser chrome-for-testing'] },
       install: { display: ctx.settings.enabled ? 'disable PLAYWRIGHT' : 'enable PLAYWRIGHT (config.json)', platforms: ['codex', 'claude', 'gemini', 'opencode'] },
     };
   },
@@ -80,11 +83,12 @@ export default defineModule({
   },
   conditions: [{
     id: 'playwright-missing',
+    code: 'MU-054',
     severity: 'informational',
     title: 'PLAYWRIGHT: the browser server is not installed',
     match: /@playwright\/mcp|playwright.*not (found|installed)|browser server/i,
-    diagnosis: 'The PLAYWRIGHT module runs @playwright/mcp per turn. It is on, or you tried to open it, but npx cannot find the package without downloading, or no browser is installed.',
-    remedy: 'Install it once, globally, then RECHECK in MODULES.',
-    fixes: { darwin: ['npm install -g @playwright/mcp', 'npx playwright install chromium'], linux: ['npm install -g @playwright/mcp', 'npx playwright install --with-deps chromium'] },
+    diagnosis: 'The PLAYWRIGHT module runs @playwright/mcp per turn. Two different things have to be on this computer and only one of them is the package: the server, and the browser build that this version of it expects. A server that starts without its browser answers every tool call with "Browser … is not installed", and one that cannot start at all reaches the agent as CONNECTION_CLOSED.',
+    remedy: 'Install the server once, globally, then its browser — the browser is downloaded by the server itself, not by the playwright CLI — and RECHECK in MODULES.',
+    fixes: { darwin: ['npm install -g @playwright/mcp', 'npx @playwright/mcp install-browser chrome-for-testing'], linux: ['npm install -g @playwright/mcp', 'npx @playwright/mcp install-browser chrome-for-testing'] },
   }],
 });

package/src/outbound.mjs

@@ -30,7 +30,12 @@ const LOCAL = new Set(['127.0.0.1', 'localhost', '::1', '0.0.0.0', '[::1]']);
 
 // Where an unknown condition goes when somebody presses SEND. It lives here because this is the
 // file that has to name every address MADRE can reach; the room reads it from here.
-export const DEFAULT_REPORT_URL = 'https://madre-reports.jossue-alcala-o.workers.dev/v1/reports';
+// The collector, under the product's own name. The address a human reads in the outbound log is
+// part of what they are being asked to trust, and a workers.dev subdomain with an account name in
+// it reads like somebody's scratch endpoint. The old address must keep answering: every room on
+// 0.4.0 and earlier carries it compiled in, and turning it off would stop their reports silently.
+export const DEFAULT_REPORT_URL = 'https://madre.run/v1/reports';
+export const LEGACY_REPORT_URL = 'https://madre-reports.jossue-alcala-o.workers.dev/v1/reports';
 
 // The declaration. `what` is the honest sentence: what a request carries, not what it is called.
 export const DESTINATIONS = [