@jossuealcala/madre 0.3.2 → 0.4.0

package/public/troubleshooting.js

@@ -1,51 +1,49 @@
+import { t } from './i18n.js';
+
 // MU/TH/UR knowledge base: known conditions, how to recognise them in the
 // room's own failure records, and the remedy as terminal commands per OS.
 //
 // Pure module (no DOM) so the catalog can be unit-tested and reused by the CLI.
 
+// The two MADRE is tested on. Every remedy below is a command written for one of these two
+// shells; a third set that nobody has ever run would be worse than none.
 export const PLATFORMS = {
   darwin: { label: 'macOS', shell: 'zsh' },
   linux: { label: 'Linux', shell: 'bash' },
-  win32: { label: 'Windows', shell: 'PowerShell' },
 };
 
 const envExport = (name, value) => ({
   darwin: [`export ${name}="${value}"`, `# persist: echo 'export ${name}="${value}"' >> ~/.zshrc`],
-  linux: [`export ${name}="${value}"`, `# persist: echo 'export ${name}="${value}"' >> ~/.bashrc`],
-  win32: [`$env:${name}="${value}"`, `# persist: setx ${name} "${value}"`],
+  linux: [`export ${name}="${value}"`, `# persist: echo 'export ${name}="${value}"' >> ~/.bashrc`]
 });
 
 const installAgent = {
   codex: {
     darwin: ['npm install -g @openai/codex', '# or install the ChatGPT desktop app, which bundles codex'],
-    linux: ['npm install -g @openai/codex'],
-    win32: ['npm install -g @openai/codex'],
+    linux: ['npm install -g @openai/codex']
   },
   claude: {
     darwin: ['brew install --cask claude-code', '# or: npm install -g @anthropic-ai/claude-code'],
-    linux: ['npm install -g @anthropic-ai/claude-code'],
-    win32: ['npm install -g @anthropic-ai/claude-code'],
+    linux: ['npm install -g @anthropic-ai/claude-code']
   },
   gemini: {
     darwin: ['npm install -g @google/gemini-cli'],
-    linux: ['npm install -g @google/gemini-cli'],
-    win32: ['npm install -g @google/gemini-cli'],
+    linux: ['npm install -g @google/gemini-cli']
   },
   opencode: {
     darwin: ['brew install opencode', '# or: npm install -g opencode-ai'],
-    linux: ['curl -fsSL https://opencode.ai/install | bash', '# or: npm install -g opencode-ai'],
-    win32: ['npm install -g opencode-ai'],
+    linux: ['curl -fsSL https://opencode.ai/install | bash', '# or: npm install -g opencode-ai']
   },
 };
 
 const loginAgent = {
-  codex: { darwin: ['codex login', 'codex login status'], linux: ['codex login', 'codex login status'], win32: ['codex login', 'codex login status'] },
-  claude: { darwin: ['claude auth login', 'claude auth status --text'], linux: ['claude auth login', 'claude auth status --text'], win32: ['claude auth login', 'claude auth status --text'] },
-  gemini: { darwin: ['gemini', '# inside gemini: /auth  → "Use Gemini API key" or Google login'], linux: ['gemini', '# inside gemini: /auth'], win32: ['gemini', '# inside gemini: /auth'] },
-  opencode: { darwin: ['opencode auth login', 'opencode auth list'], linux: ['opencode auth login', 'opencode auth list'], win32: ['opencode auth login', 'opencode auth list'] },
+  codex: { darwin: ['codex login', 'codex login status'], linux: ['codex login', 'codex login status']},
+  claude: { darwin: ['claude auth login', 'claude auth status --text'], linux: ['claude auth login', 'claude auth status --text']},
+  gemini: { darwin: ['gemini', '# inside gemini: /auth  → "Use Gemini API key" or Google login'], linux: ['gemini', '# inside gemini: /auth']},
+  opencode: { darwin: ['opencode auth login', 'opencode auth list'], linux: ['opencode auth login', 'opencode auth list']},
 };
 
-const same = (commands) => ({ darwin: commands, linux: commands, win32: commands });
+const same = (commands) => ({ darwin: commands, linux: commands });
 
 export const CONDITIONS = [
   {
@@ -58,8 +56,7 @@ export const CONDITIONS = [
     remedy: 'Switch Gemini to an API key from Google AI Studio. MADRE copies only the auth selection into its isolated home, so the key can stay in the keychain or in ~/.gemini/.env.',
     fixes: {
       darwin: ['gemini', '# inside gemini: /auth → "Use Gemini API key" and paste the key from https://aistudio.google.com/app/apikey', '# or, without the prompt:', ...envExport('GEMINI_API_KEY', 'YOUR_KEY').darwin],
-      linux: ['gemini', '# inside gemini: /auth → "Use Gemini API key"', ...envExport('GEMINI_API_KEY', 'YOUR_KEY').linux],
-      win32: ['gemini', '# inside gemini: /auth → "Use Gemini API key"', ...envExport('GEMINI_API_KEY', 'YOUR_KEY').win32],
+      linux: ['gemini', '# inside gemini: /auth → "Use Gemini API key"', ...envExport('GEMINI_API_KEY', 'YOUR_KEY').linux]
     },
   },
   {
@@ -82,8 +79,7 @@ export const CONDITIONS = [
     remedy: 'Wait a minute and retry, pick an explicit model in the composer (gemini-3-flash-preview skips the router), or raise the key\'s quota in Google AI Studio.',
     fixes: {
       darwin: ['# in the room: click the Gemini sphere twice → choose gemini-3-flash-preview', '# check quota: https://aistudio.google.com/app/apikey', 'gemini --model gemini-3-flash-preview -p "ping"'],
-      linux: ['gemini --model gemini-3-flash-preview -p "ping"', '# quota: https://aistudio.google.com/app/apikey'],
-      win32: ['gemini --model gemini-3-flash-preview -p "ping"', '# quota: https://aistudio.google.com/app/apikey'],
+      linux: ['gemini --model gemini-3-flash-preview -p "ping"', '# quota: https://aistudio.google.com/app/apikey']
     },
   },
   {
@@ -106,8 +102,7 @@ export const CONDITIONS = [
     remedy: 'Tell MADRE which provider/model OpenCode should use in the room, or remove the stale credential so the default changes.',
     fixes: {
       darwin: ['npx @jossuealcala/madre setup', '# press [m] and pick a provider/model that has a session, e.g. openai/gpt-5.6-sol', '# one-off alternative:', 'PULSE_OPENCODE_MODEL=openai/gpt-5.6-sol npx @jossuealcala/madre start', '# or drop the stale key:', 'opencode auth logout anthropic'],
-      linux: ['npx @jossuealcala/madre setup', '# press [m] and pick a provider/model that has a session', 'PULSE_OPENCODE_MODEL=openai/gpt-5.6-sol npx @jossuealcala/madre start', 'opencode auth logout anthropic'],
-      win32: ['npx @jossuealcala/madre setup', '# press [m] and pick a provider/model that has a session', '$env:PULSE_OPENCODE_MODEL="openai/gpt-5.6-sol"; npx @jossuealcala/madre start', 'opencode auth logout anthropic'],
+      linux: ['npx @jossuealcala/madre setup', '# press [m] and pick a provider/model that has a session', 'PULSE_OPENCODE_MODEL=openai/gpt-5.6-sol npx @jossuealcala/madre start', 'opencode auth logout anthropic']
     },
   },
   {
@@ -116,7 +111,7 @@ export const CONDITIONS = [
     title: 'Agent installed but signed out',
     match: /not logged in|sign in required|Error authenticating|unauthorized|please (?:log|sign) ?in|no credentials/i,
     diagnosis: 'The CLI is on this computer but has no session for its provider. MADRE never stores credentials; each agent keeps its own.',
-    remedy: 'Sign in with the agent\'s own command. `madre setup` runs these for you and rescans.',
+    remedy: 'Press SIGN IN on the agent\'s card: on first contact the room opens on the bridge, and later the same button lives in ⚙ CONNECTIONS. Codex and Claude sign in with a browser flow MADRE runs for you; Gemini and OpenCode hand you their command. `madre setup` does the same from a terminal.',
     fixes: same(['npx @jossuealcala/madre setup', '# or directly:', 'codex login', 'claude auth login', 'opencode auth login', 'gemini   # then /auth']),
     perAgent: loginAgent,
   },
@@ -126,7 +121,7 @@ export const CONDITIONS = [
     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,
     diagnosis: 'MADRE looks for `codex`, `claude`, `gemini` and `opencode` on PATH plus a few known locations. Nothing answered.',
-    remedy: 'Install the CLI, then reload the room or run `madre setup` → [r].',
+    remedy: 'Press INSTALL on the agent\'s card: MADRE shows the exact command, runs it here and looks again when it finishes, no restart. `madre setup` does the same from a terminal.',
     fixes: same(['# pick the agent you want; see per-agent commands below']),
     perAgent: installAgent,
   },
@@ -158,8 +153,7 @@ export const CONDITIONS = [
     remedy: 'Press the RAISE button on this card, or type a new number in ⚙ CONNECTIONS (DEFAULT TIMEOUT · SECONDS, or the field on the agent\'s card): fields save the moment you leave them. It applies to the next turn and persists in ~/.pulse/config.json. Environment variables work too, but only for a server started after exporting them; a running room never sees a later export.',
     fixes: {
       darwin: ['# live, no restart: ⚙ CONNECTIONS → DEFAULT TIMEOUT · SECONDS → SAVE', '# at launch only (env wins over config.json):', 'PULSE_AGENT_TIMEOUT_MS=300000 PULSE_CLAUDE_TIMEOUT_MS=600000 madre start', '# or ~/.pulse/config.json → {"timeouts":{"default":300000,"claude":600000}}'],
-      linux: ['# live, no restart: ⚙ CONNECTIONS → DEFAULT TIMEOUT · SECONDS → SAVE', 'PULSE_AGENT_TIMEOUT_MS=300000 PULSE_CLAUDE_TIMEOUT_MS=600000 madre start', '# or ~/.pulse/config.json → {"timeouts":{"default":300000,"claude":600000}}'],
-      win32: ['# live, no restart: ⚙ CONNECTIONS → DEFAULT TIMEOUT · SECONDS → SAVE', '$env:PULSE_AGENT_TIMEOUT_MS="300000"; $env:PULSE_CLAUDE_TIMEOUT_MS="600000"; madre start', '# or %USERPROFILE%\\.pulse\\config.json → {"timeouts":{"default":300000,"claude":600000}}'],
+      linux: ['# live, no restart: ⚙ CONNECTIONS → DEFAULT TIMEOUT · SECONDS → SAVE', 'PULSE_AGENT_TIMEOUT_MS=300000 PULSE_CLAUDE_TIMEOUT_MS=600000 madre start', '# or ~/.pulse/config.json → {"timeouts":{"default":300000,"claude":600000}}']
     },
   },
   {
@@ -180,8 +174,7 @@ export const CONDITIONS = [
     remedy: 'Split the message, or raise the cap if your CLIs cope.',
     fixes: {
       darwin: ['export PULSE_MAX_MESSAGE_CHARS="40000"'],
-      linux: ['export PULSE_MAX_MESSAGE_CHARS="40000"'],
-      win32: ['$env:PULSE_MAX_MESSAGE_CHARS="40000"'],
+      linux: ['export PULSE_MAX_MESSAGE_CHARS="40000"']
     },
   },
   {
@@ -202,8 +195,7 @@ export const CONDITIONS = [
     remedy: 'Continue with another agent, press RAISE LOCAL BUDGET on this card, or type a number in ⚙ CONNECTIONS → LOCAL TOKEN BUDGET PER AGENT (saves on leaving the field). The provider\'s real limits show in each sphere\'s popover when the CLI reports them.',
     fixes: {
       darwin: ['# live: ⚙ CONNECTIONS → LOCAL TOKEN BUDGET PER AGENT → SAVE', '# at launch: PULSE_SOFT_TOKEN_BUDGET=1000000 madre start', '# or ~/.pulse/config.json → {"room":{"softTokenBudget":1000000}}'],
-      linux: ['# live: ⚙ CONNECTIONS → LOCAL TOKEN BUDGET PER AGENT → SAVE', 'PULSE_SOFT_TOKEN_BUDGET=1000000 madre start'],
-      win32: ['# live: ⚙ CONNECTIONS → LOCAL TOKEN BUDGET PER AGENT → SAVE', '$env:PULSE_SOFT_TOKEN_BUDGET="1000000"; madre start'],
+      linux: ['# live: ⚙ CONNECTIONS → LOCAL TOKEN BUDGET PER AGENT → SAVE', 'PULSE_SOFT_TOKEN_BUDGET=1000000 madre start']
     },
   },
   {
@@ -215,8 +207,7 @@ export const CONDITIONS = [
     remedy: 'Use a different port, or find and stop the process holding it.',
     fixes: {
       darwin: ['npx @jossuealcala/madre start --port 4318', '# who holds 4317?', 'lsof -nP -iTCP:4317 -sTCP:LISTEN'],
-      linux: ['npx @jossuealcala/madre start --port 4318', 'ss -ltnp | grep 4317'],
-      win32: ['npx @jossuealcala/madre start --port 4318', 'netstat -ano | findstr :4317', '# then: taskkill /PID <pid> /F'],
+      linux: ['npx @jossuealcala/madre start --port 4318', 'ss -ltnp | grep 4317']
     },
   },
   {
@@ -299,11 +290,11 @@ export const CONDITIONS = [
   {
     id: 'modes',
     severity: 'informational',
-    title: 'Permission modes: #0 GHOST · #1 EXCHANGE · #2 CREATE · #3 CONTROL',
-    match: /mode|ghost|exchange|control|override|designation|max mode|#[0-3]\b/i,
-    diagnosis: 'Every message goes out at a mode, chosen in the chip after TO @agent (or typed as #2 in the text). #0 GHOST is off the record: nothing is saved, no other agent remembers it, gone on reload, no delegation. #1 EXCHANGE is the default: read and coordinate. #2 CREATE lets the agent add new files and folders anywhere in the project, where they belong; whatever existed before is put back after the turn and the room says so. #3 CONTROL puts one agent in command of the project itself: a git checkpoint is taken first, every change is listed afterwards, writes into .git, .pulse or .env files are reverted on the spot, and UNDO restores the checkpoint. One holder at a time; it needs MAX MODE 3 and a git repository. Your mode is the ceiling of any plan the message starts, and #3 is never delegated. Each agent has a MAX MODE in CONNECTIONS; above it, #2 is answered read-only and #3 is refused. When a #1 plan reaches a step that wants to create something, the room pauses and asks you: GRANT ONCE, GRANT FOR PLAN or DENY, with a 3-minute clock; silence denies.',
-    remedy: 'Pick the mode in the chip, or type #0..#3 in the message. Raise an agent\'s MAX MODE in ⚙ CONNECTIONS. CONTROL asks for the project designation (the folder name) in the override before arming.',
-    fixes: same(['# chip: TO @codex  #1 EXCHANGE ▾  → choose', '@codex #2 create the poster', '# ⚙ CONNECTIONS → agent card → MAX MODE']),
+    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,
+    diagnosis: 'Every message goes out at a mode, chosen in the chip after TO @agent (or typed as #2 in the text). #0 GHOST is off the record: nothing is saved, no other agent remembers it, gone on reload, no delegation. #1 EXCHANGE is the default: read and coordinate. #2 CREATE lets the agent add new files and folders anywhere in the project, where they belong; whatever existed before is put back after the turn and the room says so. #3 CONTROL puts one agent in command of the project itself: a git checkpoint is taken first, every change is listed afterwards, writes into .git, .pulse or .env files are reverted on the spot, and UNDO restores the checkpoint. One holder at a time; it needs MAX MODE 3 and a git repository. Your mode is the ceiling of any plan the message starts, and #3 is never delegated. Each agent has a MAX MODE in CONNECTIONS; above it, #2 is answered read-only and #3 is refused. When a #1 plan reaches a step that wants to create something, the room pauses and asks you: GRANT ONCE, GRANT FOR PLAN or DENY, with a 3-minute clock; silence denies. #4 AIRLOCK is CONTROL plus commands: tests, builds, git push, deploys with the CLIs and sessions already on this machine. Files still come back with UNDO; what leaves the machine does not, so the override asks twice: the designation, then the word AIRLOCK. An agent that says it needs a "production mode" or "permission to run commands" is asking for #4.',
+    remedy: 'Pick the mode in the chip, or type #0..#4 in the message. Raise an agent\'s MAX MODE in ⚙ CONNECTIONS. CONTROL asks for the project designation (the folder name) in the override; AIRLOCK asks for the designation and then the word AIRLOCK.',
+    fixes: same(['# chip: TO @codex  #1 EXCHANGE ▾  → choose', '@codex #2 create the poster', '@opencode #4 run the tests and deploy to preview', '# ⚙ CONNECTIONS → agent card → MAX MODE']),
   },
   {
     id: 'lease-missing',
@@ -332,8 +323,7 @@ export const CONDITIONS = [
     remedy: 'Update Node to the current LTS.',
     fixes: {
       darwin: ['node --version', 'brew install node', '# or: nvm install --lts'],
-      linux: ['node --version', 'nvm install --lts', '# or your distro package for Node ≥ 22.5'],
-      win32: ['node --version', 'winget install OpenJS.NodeJS.LTS'],
+      linux: ['node --version', 'nvm install --lts', '# or your distro package for Node ≥ 22.5']
     },
   },
   {
@@ -345,8 +335,7 @@ export const CONDITIONS = [
     remedy: 'The index is derived from the ledger: delete memory.sqlite (and its -wal/-shm siblings) and restart; MADRE rebuilds it. Distilled notes live in the same file, so export them from NOSTROMO first if they matter.',
     fixes: {
       darwin: ['node --version   # must be ≥ 22.5', 'ls ~/.pulse/rooms/*/memory.sqlite*', 'rm ~/.pulse/rooms/<room>/memory.sqlite*   # rebuilt on next start'],
-      linux: ['node --version   # must be ≥ 22.5', 'ls ~/.pulse/rooms/*/memory.sqlite*', 'rm ~/.pulse/rooms/<room>/memory.sqlite*   # rebuilt on next start'],
-      win32: ['node --version   # must be ≥ 22.5', 'dir $env:USERPROFILE\\.pulse\\rooms', 'Remove-Item $env:USERPROFILE\\.pulse\\rooms\\<room>\\memory.sqlite*'],
+      linux: ['node --version   # must be ≥ 22.5', 'ls ~/.pulse/rooms/*/memory.sqlite*', 'rm ~/.pulse/rooms/<room>/memory.sqlite*   # rebuilt on next start']
     },
   },
   {
@@ -376,8 +365,7 @@ export const CONDITIONS = [
     remedy: 'Sign the Gemini CLI in with an API key (/auth) or export GEMINI_API_KEY, then restart. If you do not want embeddings at all, set PULSE_EMBED=0 and the pause message stops.',
     fixes: {
       darwin: ['gemini   # /auth → "Use Gemini API key"', ...envExport('GEMINI_API_KEY', 'YOUR_KEY').darwin, 'PULSE_EMBED=0 madre start   # lexical only, no messages'],
-      linux: ['gemini   # /auth → "Use Gemini API key"', ...envExport('GEMINI_API_KEY', 'YOUR_KEY').linux, 'PULSE_EMBED=0 madre start'],
-      win32: ['gemini   # /auth → "Use Gemini API key"', ...envExport('GEMINI_API_KEY', 'YOUR_KEY').win32, '$env:PULSE_EMBED="0"; madre start'],
+      linux: ['gemini   # /auth → "Use Gemini API key"', ...envExport('GEMINI_API_KEY', 'YOUR_KEY').linux, 'PULSE_EMBED=0 madre start']
     },
   },
   {
@@ -389,8 +377,7 @@ export const CONDITIONS = [
     remedy: 'Update the CLI, then check that it sees the server. Codex can list servers from a config override; Claude accepts an inline --mcp-config. If a CLI keeps failing, PULSE_MEMORY_TOOLS=0 removes the tools for everyone and the room continues on automatic recall.',
     fixes: {
       darwin: ['codex mcp list', 'claude --version', 'gemini --version', 'PULSE_MEMORY_TOOLS=0 madre start   # tools off, recall stays'],
-      linux: ['codex mcp list', 'claude --version', 'gemini --version', 'PULSE_MEMORY_TOOLS=0 madre start'],
-      win32: ['codex mcp list', 'claude --version', 'gemini --version', '$env:PULSE_MEMORY_TOOLS="0"; madre start'],
+      linux: ['codex mcp list', 'claude --version', 'gemini --version', 'PULSE_MEMORY_TOOLS=0 madre start']
     },
   },
   {
@@ -429,8 +416,7 @@ export const CONDITIONS = [
     remedy: 'Install Ollama (ollama.com), start it, then in MODULES press RECHECK and PULL the models it suggests. Set PULSE_OLLAMA_MODEL or PULSE_OLLAMA_EMBED_MODEL to prefer others; PULSE_EMBED_PROVIDER=gemini keeps embeddings on Gemini even with Ollama running.',
     fixes: {
       darwin: ['brew install ollama', 'ollama serve', 'ollama pull nomic-embed-text', 'ollama pull qwen2.5:3b'],
-      linux: ['curl -fsSL https://ollama.com/install.sh | sh', 'ollama serve', 'ollama pull nomic-embed-text', 'ollama pull qwen2.5:3b'],
-      win32: ['winget install Ollama.Ollama', 'ollama serve', 'ollama pull nomic-embed-text', 'ollama pull qwen2.5:3b'],
+      linux: ['curl -fsSL https://ollama.com/install.sh | sh', 'ollama serve', 'ollama pull nomic-embed-text', 'ollama pull qwen2.5:3b']
     },
   },
   {
@@ -442,6 +428,18 @@ export const CONDITIONS = [
     remedy: 'Start Ollama and PULL a chat model in MODULES → OLLAMA; the switch @MADRE IN THE ROOM turns the agent off if you do not want it. Ask it "what did we decide about …" or "did we ever discuss …".',
     fixes: same(['ollama serve', 'ollama pull qwen2.5:3b', '@madre what did we decide about the webhook?']),
   },
+  {
+    id: 'install-needs-admin',
+    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,
+    diagnosis: 'A global npm install writes into a folder that belongs to the system. With Node installed from its own installer that folder needs an administrator, so npm stops with a permission error. MADRE does not ask for your password: when it sees that wall it installs the CLI into a folder of its own, ~/.pulse/tools, and looks there as well as along PATH. The agent works the same; only the file lives somewhere else.',
+    remedy: 'Nothing to do: press INSTALL again and MADRE takes the second way by itself. If you would rather have the CLI everywhere in your terminal, install it yourself with your package manager, or give npm a folder of your own.',
+    fixes: {
+      darwin: ['# MADRE does this for you; these are the alternatives:', 'brew install --cask claude-code', 'npm config set prefix ~/.npm-global   # then add ~/.npm-global/bin to your PATH'],
+      linux: ['# MADRE does this for you; these are the alternatives:', 'npm config set prefix ~/.npm-global   # then add ~/.npm-global/bin to your PATH']
+    },
+  },
   {
     id: 'privacy-leak',
     severity: 'warning',
@@ -460,12 +458,124 @@ export const CONDITIONS = [
     remedy: 'Read the list under the reply before moving on. If the change is wrong press UNDO; if the agent should not have had it, lower its MAX MODE in ⚙ CONNECTIONS.',
     fixes: same(['git log --oneline -5   # checkpoints are ordinary commits on a side ref', 'git stash list', '# room → UNDO under the CONTROL notice']),
   },
+  {
+    id: 'conversations',
+    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,
+    diagnosis: 'A project has one memory and many conversations. The archive, the crew, the modules and the privacy list belong to the project and do not start over when you open another thread; a conversation is only the record of one line of work, and everything said in any of them feeds the same archive. The first conversation is the ledger that was always there, so a room that existed before opens exactly as it did. The numbering is the project\'s, not the thread\'s: a new conversation starts where the project got to, which is why a citation like #1411 means the same exchange in all of them. One conversation drives the crew at a time — two threads editing the same working tree is a way to lose work — so opening another while a turn runs is refused until it finishes. And one server per project: a second `madre start` on the same project is refused with the address of the room that is already open, because two servers would hand out the same sequence twice and the archive would quietly keep one of them.',
+    remedy: 'The panel on the left of the canvas lists them: open one, or start another at the bottom. Deleting one takes its transcript and nothing else — what the archivist distilled from it is the project\'s memory and stays. If MADRE says the project is already open, use that room and open a conversation inside it instead of starting a second server.',
+    fixes: same(['# room → the handle under the bar, on the left → NEW CONVERSATION', '# the address of the open room is in the refusal itself', 'ls ~/.pulse/rooms/*/chats.json   # their names and which one is open']),
+  },
+  {
+    id: 'memory-aberrations',
+    severity: 'informational',
+    title: 'Aberrations: what the room established is false',
+    match: /aberration|aberraci|eyecat|contradict|refut|false claim|hallucinat|alucina/i,
+    diagnosis: 'An aberration is a claim the room established is false, kept on purpose rather than deleted: it is what the local model learns not to repeat. It never travels into a turn, and the note it refutes is taken out of circulation with it — a refuted memory is never recalled again, by words or by meaning. EYECAT watches for two agents saying opposite things about the same subject and raises the pair for a third agent to judge, one that took no part in either side. Confirming files the aberration and quarantines what it refutes; dismissing says the room was right and the pair is never raised again. Forgetting an aberration gives its note back.',
+    remedy: 'NOSTROMO shows them as collapsed bodies: open one to read what it took down, or clear it if the room was wrong about being wrong. The three tests report open contradictions under CONSISTENCY.',
+    fixes: same(['# room → ◉ NOSTROMO → the dark bodies are aberrations', '# ⚙ CONNECTIONS → MEMORY → THE THREE TESTS → CONSISTENCY']),
+  },
+  {
+    id: 'memory-cascade',
+    severity: 'informational',
+    title: 'Memory used · N by association',
+    match: /by association|cascade|spreading activation|keeps arriving with|memory used/i,
+    diagnosis: 'Under a reply, MADRE says what the archive handed that turn. Most of it was matched to what you asked, by words and by meaning. A note marked "by association" came along for a different reason: this room keeps carrying it in the same turn as one of the others, so the archive brings it too, however differently it reads. The strength is a ratio over the turns where each was found on its own merits — a memory the room reaches for constantly does not end up attached to everything, and a pair that stops meeting fades on its own. Association adds and never displaces: recall keeps two slots for it and hands back the ones it does not use.',
+    remedy: 'Click a note to see it in NOSTROMO, where the wires it travels on are drawn. It is the one part of recall that owes nothing to how a memory reads, so it can be switched off in MEMORY.',
+    fixes: same(['# ⚙ CONNECTIONS → MEMORY → CARRY WHAT A MEMORY KEEPS ARRIVING WITH', 'PULSE_RECALL_CASCADE=0 npx @jossuealcala/madre start']),
+  },
+  {
+    id: 'memory-cold',
+    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,
+    diagnosis: 'A memory is cold when three things are true at once: no turn has ever carried it, it shares a subject with nothing so nothing can reach it sideways either, and the archive has been opened at least a dozen times since it was written. The third is what makes the label worth acting on — never-recalled is what every memory is on the day it is written. Chances are counted in turns that actually reached into the archive, and only from the day the room started keeping that trail, so what was never written down is not held against the note.',
+    remedy: 'NOSTROMO shows COLD · N in its header when there are any; pressing it rings each one on the map. Open one and its card says the number plainly, with FORGET one press away. Asking about it is the other way out: the room writes that question for you under ASK.',
+    fixes: same(['# room → ◉ NOSTROMO → COLD', '# room → ◉ NOSTROMO → ASK → PUT IN THE COMPOSER']),
+  },
+  {
+    id: 'maturity-tests',
+    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,
+    diagnosis: 'The six readings count what the archive is made of; they cannot say whether it works, because nothing about a pile of notes says whether the right one comes back when it is needed. COVERAGE takes real questions from this room, runs recall at the exact point each was asked, and scores what came back against the reply that was actually given. CONSISTENCY reads the contradictions EYECAT still holds and whether aberrations are being filed more often lately. MATCH puts real questions a frontier CLI answered back to the local model with this archive behind it. All three measure against a control, because everything in one room is about the same handful of subjects and any two pieces of it read as close to an embedder: to count, what the archive handed over has to beat what it would have handed over for a different question.',
+    remedy: 'Read the one sentence and the one instruction at the top of MEMORY; the readings and the tests are a fold below it. The free test is read as the panel opens, the cheap one keeps itself fresh once a day while the embeddings are local, and the slow one is yours to start and to stop. None of them spends a provider turn.',
+    fixes: same(['# ⚙ CONNECTIONS → MEMORY → THE THREE TESTS', '# MATCH needs Ollama running with a chat model, and embeddings on']),
+  },
+  {
+    id: 'module-update',
+    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,
+    diagnosis: 'When something newer exists and the module knows how to fetch it, the button is beside the version on its card. It asks twice on purpose: the first press answers with the command, the second runs exactly that, and the output lands in the room line by line. Nothing installs by itself — putting software on your computer unannounced would break the one thing MADRE promises, that a command is seen before it runs. The usual failure is npm refusing a global install with EACCES, which means the global prefix belongs to root; sudo works and leaves you with root-owned files, so a user-owned prefix or a version manager is the better answer.',
+    remedy: 'Press the button beside the version, read the command, run it. If npm refuses with EACCES, point npm at a prefix you own or use a version manager, then press it again.',
+    fixes: {
+      darwin: ['npm config get prefix', 'npm config set prefix ~/.npm-global', 'echo \'export PATH="$HOME/.npm-global/bin:$PATH"\' >> ~/.zshrc', '# or: brew install node   # a Homebrew node owns its own prefix'],
+      linux: ['npm config get prefix', 'npm config set prefix ~/.npm-global', 'echo \'export PATH="$HOME/.npm-global/bin:$PATH"\' >> ~/.bashrc', '# or use nvm, which owns the prefix it installs into'],
+    },
+  },
+  {
+    id: 'module-add',
+    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,
+    diagnosis: 'MODULES has + ADD A MODULE for a .mjs somebody wrote. It comes through the same door as everything else: written to a scratch copy, imported there, checked against the house rules, and installed only if it passes. Three things get a file refused, each with the reason: an id that belongs to a module MADRE ships with, a route outside its own corner of the API (/api/x/<id>/), and a file that will not load at all. Said plainly, because it is what it is: a module runs inside MADRE, with your permissions, on this computer. MADRE checks that it loads and stays in its corral; what the code intends is the one thing nobody can check for you.',
+    remedy: 'Install it only if you trust where it came from. A module you wrote can also be updated from where you publish it: declare updates: { url } in the file, or install it from a file and MADRE remembers which, and its card carries GET A NEWER FILE.',
+    fixes: same(['# MODULES → + ADD A MODULE', 'ls ~/.pulse/modules   # every module you installed, and where it came from', '# docs/SDK.md is the whole contract, and docs/sdk/hello-module.mjs is one that works']),
+  },
+  {
+    id: 'local-ready',
+    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,
+    diagnosis: 'Running is not the same as being of use. @madre being in the room means Ollama has a chat model; whether that model is worth your work on THIS project is a different question, and the room measures it: twelve real exchanges from this room are put back to the local model, and each answer is scored against what the crew actually answered that day — against a control, so that talking about the same project does not count. It takes minutes and spends nothing, because all of it runs on your machine.',
+    remedy: 'The room says which of the two it has, once per model, in the line that begins "local · @madre". If nobody has measured it, that line carries CHECK IT AGAINST THIS ROOM; the answer lands in the room when it finishes, with the one thing to do about it. A model that does not pass is not broken — the archive is still thin, and it fills where the work happens. The @madre sphere keeps the reading and its date after the line has scrolled away, and the same test lives in NOSTROMO → THE THREE TESTS.',
+    fixes: same([
+      '# the line in the room: local · @madre → CHECK IT AGAINST THIS ROOM',
+      '# or: NOSTROMO → THE THREE TESTS → the third one',
+      '# it needs embeddings on and some turns answered by a CLI agent, which is what it compares against',
+    ]),
+  },
+  {
+    id: 'code000',
+    severity: 'blocking',
+    title: 'CODE000: the archive is sealed',
+    match: /CODE000|THE ARCHIVE IS SEALED|UNABLE TO COMPUTE\. UNABLE TO CLARIFY|designation|intruder/i,
+    diagnosis: 'Two doors ask for the project designation before doing something that cannot be undone: boarding NOSTROMO, and purging every private term already recorded. Getting that name wrong is never part of doing the work — you either know the project you are standing in or you are trying names — so MU/TH/UR counts it. Eight wrong names inside five minutes and CODE000 comes down: the archive is sealed for ten minutes, the crew is told in code, and NOSTROMO asks for the designation again.',
+    remedy: 'The designation is the name of the project folder this room was opened in, lowercase or not. Nothing was lost: the seal is a refusal to change the archive for ten minutes, not a deletion, and it lifts on its own. Reading the core is not one of those doors and never counts — it is the way in.',
+    fixes: same(['basename "$PWD"   # the designation this room asks for', '# the seal lifts on its own; MU/TH/UR › NOSTROMO asks for the name again after it does']),
+  },
+  {
+    id: 'core-console',
+    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,
+    diagnosis: 'Inside the core there is a console: MU/TH/UR answers about this room from what the page already has — the blocks of the next briefing and their words, the command that would run it, what has left this machine, how many terms privacy is protecting, where the archive stands. Nothing is asked of the crew and nothing is sent. She answers or she says she cannot, and three inquiries she cannot parse close the frame. The count is on screen from the first one and every refusal names what she would have taken.',
+    remedy: 'Nothing happened to the archive: reading what the room says in your name is not an attempt on it. Open the core again — click the star at the centre of NOSTROMO — and the count starts over. HELP lists every inquiry; READ <BLOCK> prints one block of the briefing word for word.',
+    fixes: same(['# NOSTROMO → click the core → type HELP', '# READ MEMORIES prints the block the next turn would carry', '# SPECIAL ORDER 937 is answered too']),
+  },
+  {
+    id: 'outbound',
+    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,
+    diagnosis: 'MADRE runs here and keeps what it knows in a file you own, and the list that qualifies that sentence is inside the core, under WHAT LEFT THIS MACHINE. Seven addresses, each saying what it carries and where it is switched off: the briefing, which goes to whoever runs the agent you sent the turn to; Gemini embeddings, which carry the text of your memories; the image model, which carries the prompt an agent wrote; the npm registry and GitHub, which get a package name and nothing else; the error collector, which gets a redacted condition and only with your press; and Anthropic, for how much of your Claude plan is left. Ollama is on the list to be seen staying here.',
+    remedy: 'Under the list is the log itself: every request this process made, MADRE\'s own and any a module made, because a module runs inside MADRE and cannot opt out of the wrapper. No body, no header and no query value is ever written there — only which parameters were set. An address nothing declares is reported as exactly that.',
+    fixes: same([
+      '# NOSTROMO → click the core → WHAT LEFT THIS MACHINE',
+      'cat ~/.pulse/rooms/*/outbound.jsonl | tail -20   # the same log, on disk',
+      '# embeddings, to keep memories on this computer: MU/TH/UR → MEMORY → EMBEDDINGS → OLLAMA',
+      'PULSE_UPDATE_CHECK=0 madre start   # no version checks at all',
+    ]),
+  },
 ];
 
+// Which of the two sets of commands to show first. Anything else gets macOS, and the panel says
+// which shells these are written for rather than guessing on the reader's behalf.
 export function detectPlatform(nav = globalThis.navigator) {
   const hint = `${nav?.userAgentData?.platform ?? ''} ${nav?.platform ?? ''} ${nav?.userAgent ?? ''}`.toLowerCase();
   if (/mac|iphone|ipad|darwin/.test(hint)) return 'darwin';
-  if (/win/.test(hint)) return 'win32';
   if (/linux|android|x11/.test(hint)) return 'linux';
   return 'darwin';
 }
@@ -474,13 +584,25 @@ export function detectPlatform(nav = globalThis.navigator) {
 // only match their own agent; generic ones match anyone.
 export function diagnose(errorText, agent = null) {
   const text = String(errorText ?? '');
-  return CONDITIONS.filter((condition) => (!condition.agent || !agent || condition.agent === agent) && condition.match.test(text));
+  return CONDITIONS.filter((condition) => (!condition.agent || !agent || condition.agent === agent) && condition.match.test(text)).map(said);
+}
+
+// A condition reads in the room's language; what it MATCHES does not. The `match` patterns are
+// tested against what a CLI printed, and a CLI prints English whatever the room speaks — so the
+// patterns stay exactly as they are, and only the words a person reads go through the catalogue.
+// Said at call time, because the table is built when this file is imported and the room learns
+// its language after.
+export function said(condition) {
+  return { ...condition, title: t(condition.title), diagnosis: t(condition.diagnosis), remedy: t(condition.remedy) };
 }
+export const allConditions = () => CONDITIONS.map(said);
 
 export function searchConditions(query) {
   const needle = String(query ?? '').trim().toLowerCase();
-  if (!needle) return CONDITIONS;
-  return CONDITIONS.filter((condition) => [condition.id, condition.title, condition.diagnosis, condition.remedy, condition.agent ?? '']
+  const all = allConditions();
+  if (!needle) return all;
+  // Searched in the language it is read in, plus the id and the agent, which are never translated.
+  return all.filter((condition) => [condition.id, condition.title, condition.diagnosis, condition.remedy, condition.agent ?? '']
     .join(' ').toLowerCase().includes(needle));
 }
 

package/src/adapters/claude.mjs

@@ -6,22 +6,27 @@ import { runReadonlyProcess } from './process.mjs';
 export function claudeTools({ lease = null, scopes = null } = {}) {
   const tools = ['Read', 'Glob', 'Grep'];
   if (lease) tools.push('Write', 'Edit');
+  if (lease?.airlock) tools.push('Bash');   // AIRLOCK (#4): commands, git, deploy CLIs
   if (scopes?.web) tools.push('WebFetch', 'WebSearch');
   return tools;
 }
 
-export function mcpServersFor({ imageStudio = null, memoryServer = null } = {}) {
+export function mcpServersFor({ imageStudio = null, memoryServer = null, mcpServers = [] } = {}) {
   const servers = {};
   if (memoryServer) servers[memoryServer.name] = { command: memoryServer.command, args: memoryServer.args, env: memoryServer.env };
   if (imageStudio) servers[imageStudio.name] = { command: imageStudio.command, args: imageStudio.args, env: imageStudio.env };
+  for (const server of mcpServers) servers[server.name] = { command: server.command, args: server.args ?? [], env: server.env ?? {} };
   return servers;
 }
+// Claude's permission names for a module's server: each tool, or the whole server when the list is open.
+export const claudeMcpTools = (server) => (server.tools?.length ? server.tools.map((tool) => `mcp__${server.name}__${tool}`) : [`mcp__${server.name}`]);
 
-export function buildClaudeArgs({ prompt, model = null, attachmentsDir = null, lease = null, scopes = null, imageStudio = null, memoryServer = null }) {
+export function buildClaudeArgs({ prompt, model = null, attachmentsDir = null, lease = null, scopes = null, imageStudio = null, memoryServer = null, mcpServers = [] }) {
   const tools = claudeTools({ lease, scopes });
   const mcpTools = [
     ...(memoryServer ? memoryServer.tools.map((tool) => `mcp__${memoryServer.name}__${tool}`) : []),
     ...(imageStudio ? [`mcp__${imageStudio.name}__${imageStudio.tool}`] : []),
+    ...mcpServers.flatMap(claudeMcpTools),
   ];
   const allowed = [
     'Read', 'Glob', 'Grep',
@@ -30,13 +35,14 @@ export function buildClaudeArgs({ prompt, model = null, attachmentsDir = null, l
     // CLI: a lone Write rule is denied under dontAsk), so both come together; in CREATE the room
     // restores existing files after the turn.
     ...(lease ? [`Write(//${lease.outDir}/**)`, `Edit(//${lease.outDir}/**)`] : []),
+    ...(lease?.airlock ? ['Bash'] : []),
     ...(scopes?.web ? ['WebFetch', 'WebSearch'] : []),
     ...mcpTools,
   ];
   // Only MADRE's own MCP servers ever reach Claude here; --strict-mcp-config
   // keeps the user's servers out of the isolated run.
-  const anyMcp = Boolean(imageStudio || memoryServer);
-  const mcpConfig = JSON.stringify({ mcpServers: mcpServersFor({ imageStudio, memoryServer }) });
+  const anyMcp = Boolean(imageStudio || memoryServer || mcpServers.length);
+  const mcpConfig = JSON.stringify({ mcpServers: mcpServersFor({ imageStudio, memoryServer, mcpServers }) });
   return [
     '-p',
     ...(model ? ['--model', model] : []),
@@ -95,10 +101,11 @@ export function parseClaudeOutput(output) {
   }
 }
 
-export function invokeClaude({ executable, projectRoot, prompt, timeoutMs = 120000, signal, model = null, attachments = [], lease = null, scopes = null, imageStudio = null, memoryServer = null }) {
+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 }),
+    args: buildClaudeArgs({ prompt, model, attachmentsDir: attachments[0]?.dir ?? null, lease, scopes, imageStudio, memoryServer, mcpServers }),
     cwd: projectRoot,
     env: process.env,
     timeoutMs,

package/src/adapters/codex.mjs

@@ -12,25 +12,28 @@ export function tomlValue(value) {
 // The room's memory as an MCP server for this run only: Codex reads
 // mcp_servers.<name> from its config, and -c overrides it on the command line
 // without touching the user's config.toml.
-export function codexMcpOverrides(memoryServer) {
-  if (!memoryServer) return [];
-  const key = `mcp_servers.${memoryServer.name}`;
-  return [
-    '-c', `${key}.command=${tomlValue(memoryServer.command)}`,
-    '-c', `${key}.args=${tomlValue(memoryServer.args)}`,
-    '-c', `${key}.env=${tomlValue(memoryServer.env ?? {})}`,
-  ];
+export function codexMcpOverrides(servers) {
+  const list = (Array.isArray(servers) ? servers : [servers]).filter(Boolean);
+  return list.flatMap((server) => {
+    const key = `mcp_servers.${server.name}`;
+    return [
+      '-c', `${key}.command=${tomlValue(server.command)}`,
+      '-c', `${key}.args=${tomlValue(server.args ?? [])}`,
+      '-c', `${key}.env=${tomlValue(server.env ?? {})}`,
+    ];
+  });
 }
 
-export function buildCodexArgs({ projectRoot, prompt, model = null, attachments = [], lease = null, scopes = null, memoryServer = null }) {
+export function buildCodexArgs({ projectRoot, prompt, model = null, attachments = [], lease = null, scopes = null, memoryServer = null, mcpServers = [] }) {
   const images = attachments.filter((file) => /^image\//.test(file.contentType ?? ''));
   return [
-    '--sandbox', lease ? 'workspace-write' : 'read-only',
+    // AIRLOCK (#4): commands with network, so pushes and deploys can leave; otherwise the sandbox.
+    '--sandbox', lease?.airlock ? 'danger-full-access' : lease ? 'workspace-write' : 'read-only',
     '--ask-for-approval', 'never',
     // Live web search is a global Codex flag; the human's web scope decides.
     ...(scopes?.web ? ['--search'] : []),
     '-C', lease ? lease.outDir : projectRoot,
-    ...codexMcpOverrides(memoryServer),
+    ...codexMcpOverrides([memoryServer, ...mcpServers]),
     // Image generation is a Codex feature; the human's scope decides per turn.
     ...(lease && (scopes?.imageGen === false || lease.scopes?.imageGen === false) ? ['-c', 'features.image_generation=false'] : []),
     'exec',
@@ -70,10 +73,11 @@ 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 }) {
+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 }),
+    args: buildCodexArgs({ projectRoot, prompt, model, attachments, lease, scopes, memoryServer, mcpServers }),
     cwd: lease ? lease.outDir : projectRoot,
     env: process.env,
     timeoutMs,