@jossuealcala/madre 1.0.1 → 1.0.2

package/src/modules/mcp-connect.mjs

@@ -0,0 +1,293 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
+// CONNECT MCP: MCP servers a person adds to one project, for its agents (2026-10-14).
+//
+// The settings live in the project's Settings › Connect MCP, and only there: this module has no
+// card in MODULES (`card: 'settings'`). What it does, in the order a server goes through it:
+//
+//   1. Added by hand (a command, or an address with no sign-in, a token or OAuth) or imported from
+//      the person's other apps (.mcp.json, Claude Code, Codex, Gemini CLI, Cursor, opencode.json).
+//      Secrets go to the vault; src/mcp/connect.mjs says how.
+//   2. Checked at once: MADRE starts it through the same proxy a turn uses, does the MCP
+//      handshake and reads its tools. A server that does not answer stays out of every turn and
+//      its row says why, so a broken server costs a line in Settings, never a turn.
+//   3. Handed to the turns of this project, through src/mcp/proxy.mjs, with the tools that read
+//      from #1 and the ones that act from the mode chosen for it (#4 unless lowered).
+
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { defineModule } from './sdk.mjs';
+import { summary as vaultSummary } from '../vault.mjs';
+import { declareDestinations } from '../outbound.mjs';
+import { t } from '../i18n.mjs';
+import {
+  ACTION_MODES, SERVER_ID, authorizeUrl, cleanServer, discoverOAuth, exchangeCode, forgetServerSecrets,
+  grantFrom, importable, keepOAuth, keepSecrets, pkce, readMcp, readOAuth, registerClient, writeMcp,
+} from '../mcp/connect.mjs';
+
+export const PROXY = fileURLToPath(new URL('../mcp/proxy.mjs', import.meta.url));
+const CHECK_MS = 30000;
+
+// The argv every CLI is given for a connected server: the proxy, the project and the server. No
+// secret, ever; the allowed tools travel so the proxy can refuse the others.
+export const proxyArgs = ({ stateRoot, projectRoot, id, allow = null }) => [PROXY, '--state', stateRoot, '--project', projectRoot, '--server', id, ...(allow ? ['--allow', allow.join(',')] : [])];
+
+// Starts the server the way a turn would and asks it what it has. Resolves with its tools — each
+// with whether it only reads — or with the reason it did not answer.
+export function checkServer({ stateRoot, projectRoot, id, timeoutMs = CHECK_MS, command = process.execPath }) {
+  return new Promise((resolve) => {
+    let child;
+    let out = '';
+    let err = '';
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { child?.stdin.end(); child?.kill('SIGTERM'); } catch { /* gone */ }
+      resolve(result);
+    };
+    const timer = setTimeout(() => finish({ ok: false, problem: t('it did not answer within {seconds}s', { seconds: Math.round(timeoutMs / 1000) }) }), timeoutMs);
+    try {
+      child = spawn(command, proxyArgs({ stateRoot, projectRoot, id }), { cwd: projectRoot, stdio: ['pipe', 'pipe', 'pipe'], shell: false, windowsHide: true });
+    } catch (error) { finish({ ok: false, problem: error.message }); return; }
+    const send = (message) => { if (!settled) child.stdin.write(`${JSON.stringify(message)}\n`); };
+    child.stdin.on('error', () => {});
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => { err = `${err}${chunk}`.slice(-2000); });
+    child.on('error', (error) => finish({ ok: false, problem: error.message }));
+    child.on('close', (code) => finish({ ok: false, problem: lastLine(err) ?? t('it exited with code {code} before it spoke', { code }) }));
+    let info = null;
+    child.stdout.on('data', (chunk) => {
+      out += chunk;
+      for (let newline = out.indexOf('\n'); newline >= 0; newline = out.indexOf('\n')) {
+        const line = out.slice(0, newline).trim();
+        out = out.slice(newline + 1);
+        let message;
+        try { message = JSON.parse(line); } catch { continue; }
+        if (message.id === 1) {
+          if (message.error) { finish(authFailure(message.error.message) ?? { ok: false, problem: String(message.error.message ?? 'initialize failed').slice(0, 300) }); return; }
+          info = message.result?.serverInfo ?? null;
+          send({ jsonrpc: '2.0', method: 'notifications/initialized' });
+          send({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+        } else if (message.id === 2) {
+          if (message.error) { finish(authFailure(message.error.message) ?? { ok: false, problem: String(message.error.message ?? 'tools/list failed').slice(0, 300) }); return; }
+          const tools = (message.result?.tools ?? []).filter((tool) => typeof tool?.name === 'string').slice(0, 200).map((tool) => ({
+            name: tool.name,
+            readOnly: tool.annotations?.readOnlyHint === true,
+            description: String(tool.description ?? '').replace(/\s+/g, ' ').trim().slice(0, 160),
+          }));
+          finish({ ok: true, tools, server: info ? { name: String(info.name ?? ''), version: String(info.version ?? '') } : null });
+          return;
+        }
+      }
+    });
+    send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'madre', version: '1' } } });
+  });
+}
+const lastLine = (text) => String(text ?? '').trim().split('\n').filter(Boolean).at(-1)?.replace(/^MADRE MCP [^:]+:\s*/, '').slice(0, 300) ?? null;
+const authFailure = (message) => (/MADRE_AUTH_REQUIRED/.test(String(message ?? '')) ? { ok: false, needsAuth: true, problem: /refused the credentials/.test(String(message)) ? t('The server refused the credentials. Check the token.') : t('Sign in to this server again.') } : null);
+
+// What a turn is handed for one server: the tools that read, and the ones that act when the mode
+// allows them. Nothing for a ghost, nothing unchecked, nothing for an agent it was not given to.
+export function serverForTurn(server, { stateRoot, projectRoot, agent, mode }) {
+  if (!server.enabled || server.problem || !server.tools?.length || mode === 0) return null;
+  if (server.agents && !server.agents.includes(agent)) return null;
+  const reading = server.tools.filter((tool) => tool.readOnly).map((tool) => tool.name);
+  const acting = server.tools.filter((tool) => !tool.readOnly).map((tool) => tool.name);
+  const actionsFrom = ACTION_MODES.includes(server.actions) ? server.actions : 4;
+  const acts = mode >= actionsFrom;
+  const tools = acts ? [...reading, ...acting] : reading;
+  if (!tools.length) return null;
+  return {
+    name: server.id,
+    command: process.execPath,
+    args: proxyArgs({ stateRoot, projectRoot, id: server.id, allow: tools }),
+    env: {},
+    tools,
+    // The core keeps the rule for #4 itself: tools that act and need #4 are declared as sending.
+    sends: actionsFrom === 4 ? acting : [],
+    brief: `${server.label}${server.server?.name && server.server.name !== server.label ? ` (${server.server.name})` : ''}, connected by the human for this project.${acting.length ? acts ? ' Its tools that act are on in this turn: say what you will do before calling one.' : ` Only its tools that read are on; the ones that act need #${actionsFrom}.` : ''}`,
+  };
+}
+
+// What Settings shows: everything but values. Whether a secret is held is said by name.
+async function publicServers(ctx) {
+  const { servers } = await readMcp(ctx.stateRoot, ctx.projectRoot);
+  const held = new Set((await vaultSummary(ctx.stateRoot, 'mcp').catch(() => [])).map((one) => one.name));
+  return Promise.all(servers.map(async (server) => ({
+    ...server,
+    signedIn: server.auth === 'oauth' ? Boolean((await readOAuth(ctx.stateRoot, server.id))?.access_token) : undefined,
+    tokenHeld: server.auth === 'token' ? held.has(`${server.id}_token`) : undefined,
+  })));
+}
+
+async function saveChecked(ctx, server) {
+  const check = await checkServer({ stateRoot: ctx.stateRoot, projectRoot: ctx.projectRoot, id: server.id });
+  const { servers } = await readMcp(ctx.stateRoot, ctx.projectRoot);
+  const next = servers.map((one) => (one.id === server.id ? {
+    ...one,
+    tools: check.ok ? check.tools : one.tools,
+    server: check.ok ? check.server : one.server ?? null,
+    checkedAt: new Date().toISOString(),
+    problem: check.ok ? null : check.problem,
+    needsAuth: check.needsAuth || undefined,
+  } : one));
+  await writeMcp(ctx.stateRoot, ctx.projectRoot, { servers: next });
+  await ctx.record('mcp.checked', { id: server.id, ok: check.ok, tools: check.ok ? check.tools.length : undefined, problem: check.ok ? undefined : check.problem });
+  return check;
+}
+
+// A refusal of cleanServer, in the room's language: its slots filled, a command's reason too.
+const said = ({ error, errorArgs = {} }) => t(error, { ...errorArgs, ...(errorArgs.why ? { why: t(errorArgs.why, errorArgs.whyArgs ?? {}) } : {}) });
+const refuseFromPhone = (viaPhone) => (viaPhone ? { status: 403, body: { error: t('MCP servers are connected from the computer, not from the phone.') } } : null);
+// Sign-ins in flight: the state the server will send back, and what is needed to finish.
+const pending = new Map();   // state -> { id, verifier, clientId, redirectUri, authorization, resource, at }
+
+export default defineModule({
+  id: 'mcp',
+  name: 'Outside tools (MCP)',
+  vendor: 'MADRE',
+  version: '1.0.0',
+  summary: 'MCP servers you add to this project, for its agents: a command on this computer or an address on the internet. Each one is started and checked before any agent can use it; tools that read work from #1, tools that act from the mode you choose.',
+  creates: ['the list of servers, kept in MADRE\'s own folder for this project, never inside the project', 'its secrets in MADRE\'s vault, never in the list'],
+  requires: ['nothing; a server is checked when you add it'],
+  card: 'settings',
+  settings: { enabled: true },
+  async status(ctx) {
+    const { servers } = await readMcp(ctx.stateRoot, ctx.projectRoot);
+    const ready = servers.filter((one) => one.enabled && !one.problem && one.tools?.length).length;
+    return { status: { installed: true, detail: servers.length ? t('{ready} of {total} tools ready', { ready, total: servers.length }) : t('no tools yet') } };
+  },
+  async toolsForTurn(ctx, turn) {
+    const { servers } = await readMcp(ctx.stateRoot, ctx.projectRoot);
+    return servers.map((server) => serverForTurn(server, { stateRoot: ctx.stateRoot, projectRoot: ctx.projectRoot, agent: turn.agent, mode: Number(turn.mode) })).filter(Boolean);
+  },
+  routes: [
+    { method: 'GET', path: '/api/x/mcp/servers', async handler(ctx) { return { status: 200, body: { servers: await publicServers(ctx) } }; } },
+    {
+      method: 'POST', path: '/api/x/mcp/servers',
+      async handler(ctx, { payload, viaPhone }) {
+        const refused = refuseFromPhone(viaPhone); if (refused) return refused;
+        const { servers } = await readMcp(ctx.stateRoot, ctx.projectRoot);
+        const before = servers.find((one) => one.id === payload?.id);
+        const made = cleanServer({ ...payload, replace: Boolean(payload?.replace && before) }, { existing: servers });
+        if (made.error) return { status: 400, body: { error: said(made) } };
+        const kept = await keepSecrets(ctx.stateRoot, made.secrets);
+        if (!kept.ok) return { status: 400, body: { error: t(kept.error) } };
+        // An edit keeps what the check learned until it is checked again.
+        const server = before ? { ...made.server, tools: before.tools, server: before.server } : made.server;
+        await writeMcp(ctx.stateRoot, ctx.projectRoot, { servers: [...servers.filter((one) => one.id !== server.id), server] });
+        await ctx.record('mcp.connected', { id: server.id, transport: server.transport, auth: server.auth });
+        const check = server.auth === 'oauth' && !(await readOAuth(ctx.stateRoot, server.id))?.access_token ? { ok: false, needsAuth: true } : await saveChecked(ctx, server);
+        return { status: 200, body: { check, servers: await publicServers(ctx) } };
+      },
+    },
+    {
+      method: 'POST', path: /^\/api\/x\/mcp\/servers\/([a-z][a-z0-9-]{0,30})\/(check|toggle|actions|agents|remove)$/,
+      async handler(ctx, { payload, params: [id, what], viaPhone }) {
+        const refused = refuseFromPhone(viaPhone); if (refused) return refused;
+        const { servers } = await readMcp(ctx.stateRoot, ctx.projectRoot);
+        const server = servers.find((one) => one.id === id);
+        if (!server) return { status: 404, body: { error: t('That server is not connected in this project.') } };
+        if (what === 'check') return { status: 200, body: { check: await saveChecked(ctx, server), servers: await publicServers(ctx) } };
+        if (what === 'remove') {
+          await forgetServerSecrets(ctx.stateRoot, server);
+          await writeMcp(ctx.stateRoot, ctx.projectRoot, { servers: servers.filter((one) => one.id !== id) });
+          await ctx.record('mcp.removed', { id });
+          return { status: 200, body: { servers: await publicServers(ctx) } };
+        }
+        const change = what === 'toggle' ? { enabled: payload?.enabled === true }
+          : what === 'actions' ? { actions: ACTION_MODES.includes(Number(payload?.actions)) ? Number(payload.actions) : server.actions }
+            : { agents: Array.isArray(payload?.agents) && payload.agents.length ? payload.agents.filter((one) => /^[a-z0-9_-]+$/.test(one)) : null };
+        await writeMcp(ctx.stateRoot, ctx.projectRoot, { servers: servers.map((one) => (one.id === id ? { ...one, ...change } : one)) });
+        return { status: 200, body: { servers: await publicServers(ctx) } };
+      },
+    },
+    // What the person's other apps already have: names, places and what kind; never a value.
+    {
+      method: 'GET', path: '/api/x/mcp/import',
+      async handler(ctx, { viaPhone }) {
+        const refused = refuseFromPhone(viaPhone); if (refused) return refused;
+        const found = await importable({ projectRoot: ctx.projectRoot });
+        const { servers } = await readMcp(ctx.stateRoot, ctx.projectRoot);
+        return { status: 200, body: { found: found.map((one, index) => ({ index, source: one.source, name: one.name, id: one.id, transport: one.transport, where: one.url ?? one.command?.join(' ') ?? '', env: Object.keys(one.env ?? {}), headers: Object.keys(one.headers ?? {}), disabled: one.disabled, taken: servers.some((server) => server.id === one.id) })) } };
+      },
+    },
+    {
+      method: 'POST', path: '/api/x/mcp/import',
+      async handler(ctx, { payload, viaPhone }) {
+        const refused = refuseFromPhone(viaPhone); if (refused) return refused;
+        const found = await importable({ projectRoot: ctx.projectRoot });
+        const picks = (Array.isArray(payload?.picks) ? payload.picks : []).map(Number).filter((index) => Number.isInteger(index) && found[index]);
+        const results = [];
+        for (const index of picks) {
+          const one = found[index];
+          const { servers } = await readMcp(ctx.stateRoot, ctx.projectRoot);
+          // Every value an app kept is treated as a secret: the vault is the only place it goes.
+          const quote = (word) => (/[\s"'\\$`|&;<>()*?[#~]/.test(word) ? `'${String(word).replace(/'/g, '')}'` : word);
+          const made = cleanServer({
+            id: one.id, label: one.name, transport: one.transport, url: one.url, auth: one.url && Object.keys(one.headers ?? {}).some((name) => name.toLowerCase() === 'authorization') ? 'none' : 'none',
+            command: one.command ? one.command.map(quote).join(' ') : '',
+            env: Object.entries(one.env ?? {}).map(([name, value]) => ({ name, value: String(value), secret: true })),
+            headers: Object.entries(one.headers ?? {}).map(([name, value]) => ({ name, value: String(value), secret: true })),
+            enabled: !one.disabled,
+          }, { existing: servers });
+          if (made.error) { results.push({ id: one.id, ok: false, problem: said(made) }); continue; }
+          const kept = await keepSecrets(ctx.stateRoot, made.secrets);
+          if (!kept.ok) { results.push({ id: one.id, ok: false, problem: t(kept.error) }); continue; }
+          await writeMcp(ctx.stateRoot, ctx.projectRoot, { servers: [...servers, made.server] });
+          await ctx.record('mcp.connected', { id: made.server.id, transport: made.server.transport, auth: made.server.auth, from: one.source });
+          const check = await saveChecked(ctx, made.server);
+          results.push({ id: made.server.id, ok: check.ok, problem: check.problem, needsAuth: check.needsAuth });
+        }
+        return { status: 200, body: { results, servers: await publicServers(ctx) } };
+      },
+    },
+    // OAuth: the page asks for the address to open; the server comes back to the callback below.
+    {
+      method: 'POST', path: /^\/api\/x\/mcp\/servers\/([a-z][a-z0-9-]{0,30})\/signin$/,
+      async handler(ctx, { params: [id], viaPhone, url }) {
+        const refused = refuseFromPhone(viaPhone); if (refused) return refused;
+        const { servers } = await readMcp(ctx.stateRoot, ctx.projectRoot);
+        const server = servers.find((one) => one.id === id && one.transport === 'http');
+        if (!server) return { status: 404, body: { error: t('That server is not connected in this project.') } };
+        // MADRE's own process reaches this server to sign in: the list of what left the machine
+        // names it as the server the person connected, not as an address nothing declares.
+        declareDestinations('mcp', [{ id: server.id, host: new URL(server.url).hostname, to: t('{name} · an MCP server you connected', { name: server.label }), what: t('the sign-in: how to sign in, the registration of MADRE and the token'), when: t('when you press Sign in on it'), where: t('Settings › Outside tools (MCP)') }]);
+        const found = await discoverOAuth(server.url).catch((error) => ({ ok: false, problem: error.message }));
+        if (!found.ok) return { status: 409, body: { error: t(found.problem) } };
+        const redirectUri = `${url.origin}/api/x/mcp/oauth/callback`;
+        const client = await registerClient(found.authorization, redirectUri).catch((error) => ({ ok: false, problem: error.message }));
+        if (!client.ok) return { status: 409, body: { error: t('The server did not let MADRE register: {problem}', { problem: client.problem }) } };
+        const { verifier, challenge } = pkce();
+        const state = randomBytes(18).toString('hex');
+        for (const [key, one] of pending) if (Date.now() - one.at > 15 * 60000) pending.delete(key);
+        pending.set(state, { id, verifier, clientId: client.clientId, redirectUri, authorization: found.authorization, resource: found.resource, at: Date.now() });
+        return { status: 200, body: { open: authorizeUrl({ authorization: found.authorization, clientId: client.clientId, redirectUri, challenge, state, resource: found.resource, scopes: found.scopes }) } };
+      },
+    },
+    {
+      method: 'GET', path: '/api/x/mcp/oauth/callback',
+      async handler(ctx, { url }) {
+        const page = (title, text) => ({ status: 200, html: `<!doctype html><meta charset="utf-8"><title>MADRE</title><body style="font:15px system-ui;margin:12vh auto;max-width:34em;padding:0 16px;color:#1d2321"><h1 style="font-size:20px">${title}</h1><p>${text}</p></body>` });
+        const state = url.searchParams.get('state') ?? '';
+        const flow = pending.get(state);
+        pending.delete(state);
+        if (!flow) return page(t('This sign-in expired'), t('Sign in again from Settings › Outside tools (MCP).'));
+        if (url.searchParams.get('error')) return page(t('The sign-in was not completed'), t('The server said: {problem}', { problem: String(url.searchParams.get('error_description') ?? url.searchParams.get('error')).replace(/[<>&]/g, '') }));
+        const done = await exchangeCode({ authorization: flow.authorization, clientId: flow.clientId, redirectUri: flow.redirectUri, code: url.searchParams.get('code') ?? '', verifier: flow.verifier, resource: flow.resource }).catch((error) => ({ ok: false, problem: error.message }));
+        if (!done.ok) return page(t('The sign-in was not completed'), t('The server said: {problem}', { problem: String(done.problem).replace(/[<>&]/g, '') }));
+        await keepOAuth(ctx.stateRoot, flow.id, { ...grantFrom(done.tokens), token_endpoint: flow.authorization.token_endpoint, client_id: flow.clientId, resource: flow.resource });
+        const { servers } = await readMcp(ctx.stateRoot, ctx.projectRoot);
+        const server = servers.find((one) => one.id === flow.id);
+        const check = server ? await saveChecked(ctx, server) : { ok: false };
+        return page(check.ok ? t('Connected') : t('Signed in'), check.ok ? t('{name} is connected to this project with {n} tools. You can close this tab and go back to MADRE.', { name: server?.label ?? flow.id, n: check.tools.length }) : t('You are signed in, but the server did not answer yet: {problem}. Check it again from Settings › Outside tools (MCP).', { problem: String(check.problem ?? '').replace(/[<>&]/g, '') }));
+      },
+    },
+  ],
+});
+
+export { SERVER_ID };

package/src/modules/ollama.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // OLLAMA: local intelligence. Embeddings and distillation on this machine when
 // Ollama runs. The server offers the wiring through ctx.services.ollama.
 
@@ -49,7 +51,7 @@ export default defineModule({
   name: 'Local AI',
   vendor: 'MADRE · LOCAL INTELLIGENCE',
   tracks: { name: 'ollama', github: 'ollama/ollama' },
-  summary: 'Recall by meaning and memory distillation on this machine, through Ollama: no provider tokens, nothing leaves.',
+  summary: 'Searches and sums up the project\'s memory with local AI (Ollama): free, and nothing leaves your computer.',
   creates: ['nothing in the project', 'a block in ~/.pulse/config.json', 'models in Ollama\'s own store when you press PULL'],
   requires: ['Ollama running (the app, or ollama serve)', 'an embedding model and a chat model \u00b7 MADRE can pull the recommended ones'],
   settings: { enabled: true, embeddings: true, archivist: true, agent: true },

package/src/modules/playwright.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // PLAYWRIGHT: a headless browser for the crew, pointed only at this MADRE. Agents open the
 // RIPLEY preview of project files, click, read the console and take screenshots into the turn's
 // scratch folder. Runs @playwright/mcp per turn, isolated, with allowed origins limited to the
@@ -14,6 +16,10 @@ import { terminateProcessTree, lastWords } from '../adapters/process.mjs';
 
 export const PLAYWRIGHT_PACKAGE = '@playwright/mcp';
 export const PLAYWRIGHT_BROWSERS = ['chromium', 'firefox', 'webkit'];
+// The browser the server downloads for each engine: `install-browser` is `playwright install <name>`
+// underneath, so the name is the engine's own. The remedy used to say chrome-for-testing whatever
+// was chosen, and a person on webkit installed a browser that could never fix it (2026-10-14).
+export const installBrowserLine = (browser = 'chromium') => `npx ${PLAYWRIGHT_PACKAGE} install-browser ${PLAYWRIGHT_BROWSERS.includes(browser) ? browser : 'chromium'}`;
 export const PLAYWRIGHT_SERVER_NAME = 'pulse-playwright';
 // The tools @playwright/mcp exposes that a room turn may use. Screenshots and files land in scratch.
 export const PLAYWRIGHT_TOOLS = ['browser_navigate', 'browser_navigate_back', 'browser_snapshot', 'browser_click', 'browser_type', 'browser_fill_form', 'browser_hover', 'browser_press_key', 'browser_select_option', 'browser_wait_for', 'browser_console_messages', 'browser_network_requests', 'browser_take_screenshot', 'browser_resize', 'browser_tabs', 'browser_close'];
@@ -101,15 +107,18 @@ export const wantsBrowser = (text) => BROWSER_INTENT.test(String(text ?? ''));
 // The last answer to «does it start?», for a switch that was already on: asked again in the
 // background at most every ten minutes, so the card can say the browser is missing and no turn
 // carries a server that would only fail.
-let started = { at: 0, result: null, asking: null };
+// The answer belongs to the browser it was asked about: chosen another, it is asked again, or a
+// browser that does not start would ride on the answer of one that does.
+let started = { at: 0, result: null, asking: null, browser: null };
 export function playwrightHealth({ browser = 'chromium', env = process.env, cwd = process.cwd(), now = Date.now(), check = playwrightStarts } = {}) {
   if (env.PULSE_PLAYWRIGHT_CHECK === '0') return started.result;
+  if (started.browser !== browser) started = { at: 0, result: null, asking: null, browser };
   if (!started.asking && now - started.at > 10 * 60 * 1000) {
-    started.asking = check({ browser, env, cwd }).then((result) => { started = { at: Date.now(), result, asking: null }; return result; }, () => { started.asking = null; return null; });
+    started.asking = check({ browser, env, cwd }).then((result) => { if (started.browser === browser) started = { at: Date.now(), result, asking: null, browser }; return result; }, () => { started.asking = null; return null; });
   }
   return started.result;
 }
-export function forgetPlaywrightHealth(result = null) { started = { at: result ? Date.now() : 0, result, asking: null }; }
+export function forgetPlaywrightHealth(result = null, browser = null) { started = { at: result ? Date.now() : 0, result, asking: null, browser }; }
 
 // What the browser may open: this room, and the servers the human started from RUNS in this project
 // while they listen on 127.0.0.1. RIPLEY's sealed frame keeps no data, so an app that stores its
@@ -141,7 +150,7 @@ export default defineModule({
   tracks: { name: PLAYWRIGHT_PACKAGE, npm: PLAYWRIGHT_PACKAGE },
   summary: 'Hands an agent a headless browser that reaches only this project and the servers you start from COMMANDS, on the turns that ask to look at a page, click through it, read its console or take screenshots.',
   creates: ['nothing in the project \u00b7 screenshots land in .pulse/out/<turn>/', 'a switch in ~/.pulse/config.json', 'a browser per turn, started and stopped by the CLI', 'no origin but this project is reachable through it'],
-  requires: ['@playwright/mcp and a chromium browser on this machine', 'PREVIEW on, to have pages to open'],
+  requires: ['@playwright/mcp and the browser you choose for it (chromium by default) on this machine', 'PREVIEW on, to have pages to open'],
   settings: { enabled: false, browser: 'chromium', headless: true },
   card: 'switch',
   controls: [
@@ -154,8 +163,8 @@ export default defineModule({
     return {
       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 · the browser server is not installed') : health?.ok === false ? t('on · the browser does not start: {problem}', { problem: String(health.problem).slice(0, 160) }) : `${t('on')} · ${ctx.settings.browser}`) : 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, then its browser: npx @playwright/mcp install-browser chrome-for-testing'] },
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? (!version ? t('on · the browser server is not installed') : health?.ok === false ? t('on · the browser does not start: {problem}. Install it with {command}.', { problem: String(health.problem).replace(/[.\s]+$/, '').slice(0, 160), command: installBrowserLine(ctx.settings.browser) }) : `${t('on')} · ${ctx.settings.browser}`) : 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, then its browser: ${installBrowserLine(ctx.settings.browser)}`] },
       install: { display: ctx.settings.enabled ? 'disable PLAYWRIGHT' : 'enable PLAYWRIGHT (config.json)', platforms: ['codex', 'claude', 'gemini', 'opencode'] },
     };
   },
@@ -187,9 +196,15 @@ export default defineModule({
   async toggle(ctx) {
     const enabled = !ctx.settings.enabled;
     if (enabled) {
-      const check = await playwrightStarts({ browser: ctx.settings.browser ?? 'chromium', env: ctx.env, cwd: ctx.projectRoot });
-      forgetPlaywrightHealth(check);
-      if (!check.ok) return { status: 412, body: { error: t('TEST BROWSER did not start, so it stays off: {problem}. Install the server and its browser (npm install -g @playwright/mcp, then npx @playwright/mcp install-browser chrome-for-testing) and turn it on again.', { problem: String(check.problem).replace(/[.\s]+$/, '') }), code: 'MU-054' } };
+      const browser = ctx.settings.browser ?? 'chromium';
+      const check = await playwrightStarts({ browser, env: ctx.env, cwd: ctx.projectRoot });
+      forgetPlaywrightHealth(check, browser);
+      // The server is there and only the browser is missing: say which one, and the one line that
+      // installs it. Without the server, both lines.
+      const version = await playwrightVersion({ env: ctx.env, projectRoot: ctx.projectRoot });
+      if (!check.ok) return { status: 412, body: { error: version
+        ? t('TEST BROWSER did not start, so it stays off: {problem}. The browser server is installed; what is missing is the {browser} browser. Install it with {command} and turn it on again, or choose another browser in its settings.', { problem: String(check.problem).replace(/[.\s]+$/, ''), browser, command: installBrowserLine(browser) })
+        : t('TEST BROWSER did not start, so it stays off: {problem}. Install the server and its browser ({server}, then {command}) and turn it on again.', { problem: String(check.problem).replace(/[.\s]+$/, ''), server: `npm install -g ${PLAYWRIGHT_PACKAGE}`, command: installBrowserLine(browser) }), code: 'MU-054' } };
     }
     await ctx.updateConfig({ modules: { playwright: { ...(ctx.config.modules?.playwright ?? {}), enabled } } });
     await ctx.record('extension.toggled', { id: 'playwright', name: 'PLAYWRIGHT', enabled });
@@ -203,6 +218,6 @@ export default defineModule({
     match: /@playwright\/mcp|playwright.*not (found|installed)|browser server/i,
     diagnosis: 'The TEST BROWSER 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'] },
+    fixes: { darwin: ['npm install -g @playwright/mcp', 'npx @playwright/mcp install-browser chromium'], linux: ['npm install -g @playwright/mcp', 'npx @playwright/mcp install-browser chromium'] },
   }],
 });

package/src/modules/ripley.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // RIPLEY: the file viewer renders HTML, SVG and Markdown inside a sealed frame.
 // A switch in config.json, read live by the preview route.
 

package/src/modules/runs.mjs

@@ -1,9 +1,11 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Runs: letting an agent ask the human to run a command instead of asking them to copy it.
 //
 // Below #4 AIRLOCK an agent cannot run anything, and some answers turn on a command anyway: the
 // tests after a fix, a build, a linter. This gives that request a shape — a fenced block the room
-// turns into one button per command — and brings the output back to the room as a card every
-// agent reads on its next turn.
+// turns into one button per command — and brings the output back to the room as a card, and to
+// the agent that asked in a turn of its own once every line has run (src/room/returns.mjs).
 //
 // Nothing an agent writes runs by itself. Each line is pressed by the human, runs alone from the
 // project root with no shell, and is photographed first so UNDO can put the files back. What a
@@ -22,7 +24,7 @@ export default defineModule({
   name: 'Commands',
   vendor: 'MADRE',
   version: '1.0.0',
-  summary: 'Lets an agent ask you to run a command it cannot run in its mode (tests, a build, a linter). Each command is a button: nothing runs until you press it, it runs from the project root with no shell, a restore point is taken first, and the output comes back to the project. Costs about 300 tokens of instruction per turn below FULL ACCESS while it is on.',
+  summary: 'Lets an agent ask you to run a command it cannot run in its mode (tests, a build, a linter). Each command is a button: nothing runs until you press it, it runs from the project root with no shell, a restore point is taken first, and when it has run the output goes back to the agent that asked, which goes on. Costs about 300 tokens of instruction per turn below FULL ACCESS while it is on.',
   creates: ['nothing in the project', 'a switch in ~/.pulse/config.json'],
   async status(ctx) {
     return {

package/src/modules/sdk.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // MADRE's module SDK. A module is one file: what it is, the settings it keeps
 // in ~/.pulse/config.json, how it describes itself to MODULES, what its switch
 // does, the routes it serves and the events it listens to. The server builds a

package/src/modules/updates.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Is there a newer version of what a module is? Two kinds of answer, because there are two kinds
 // of module.
 //

package/src/mother.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // MU/TH/UR's private channel. When someone strikes at her memory core, MOTHER
 // tells her children (the agents) in a code the console cannot read; the room
 // shows the code, the agents get the words. The channel lives in

package/src/ollama.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Ollama: the local intelligence MADRE leans on when it is there. Embeddings
 // for recall by meaning and a model to distil memories, both on this machine,
 // so remembering costs no tokens elsewhere and nothing leaves. Nothing here is

package/src/outbound.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // What left this machine.
 //
 // MADRE runs on your computer and keeps everything it knows in a file you own, and that sentence
@@ -48,7 +50,7 @@ export const DESTINATIONS = [
     inside: false,
   },
   {
-    id: 'embeddings', host: 'generativelanguage.googleapis.com', match: (url) => /batchEmbedContents/.test(url.pathname), to: 'Google · Gemini embeddings',
+    id: 'embeddings', host: 'generativelanguage.googleapis.com', match: (url) => /batchEmbedContents/.test(url.pathname), to: 'Google · Gemini search by meaning',
     what: 'The text of what is being embedded: the first 2000 characters of each memory, and the question a recall is made of.',
     when: 'a memory is written or recalled, while embeddings are set to Gemini',
     where: 'Settings › Memory › Smart search · Ollama keeps it on this computer, off drops back to words',
@@ -57,7 +59,7 @@ export const DESTINATIONS = [
   {
     id: 'image', host: 'generativelanguage.googleapis.com', match: (url) => /generateContent/.test(url.pathname), to: 'Google · Gemini image model',
     what: 'The prompt an agent wrote for an image.',
-    when: 'an agent calls the image tool during a lease',
+    when: 'an agent uses the image tool during a permission to create',
     where: 'Modules › Images',
     // It runs in a process of its own and writes its own line into this same log, so it is here.
     inside: true,
@@ -65,7 +67,7 @@ export const DESTINATIONS = [
   {
     id: 'npm', host: 'registry.npmjs.org', to: 'the npm registry',
     what: 'The name of a package, to read the version of its latest release. Nothing about you or your project.',
-    when: 'at most once a day per package, while the release channel is on',
+    when: 'at most once a day per package, while Look for new versions is on',
     where: 'Settings › Version and reports › Look for new versions · or PULSE_UPDATE_CHECK=0',
     inside: true,
   },
@@ -73,7 +75,7 @@ export const DESTINATIONS = [
     // Only the release read: the rest of api.github.com is the GitHub module's, and says so itself.
     id: 'github', host: 'api.github.com', match: (url) => /\/releases\/latest$/.test(url.pathname), to: 'GitHub',
     what: 'The name of a repository, to read the tag of its latest release. Nothing about you or your project.',
-    when: 'at most once a day per repository, while the release channel is on',
+    when: 'at most once a day per repository, while Look for new versions is on',
     where: 'Settings › Version and reports › Look for new versions · or PULSE_UPDATE_CHECK=0',
     inside: true,
   },
@@ -344,7 +346,7 @@ export function outboundView({ log = null, state = {}, agents = [] } = {}) {
     recent: log?.recent({ limit: 40 }) ?? [],
     undeclared,
     says: undeclared
-      ? (undeclared === 1 ? t('1 request went to an address nothing here declares. A module can do that; nothing can do it unlogged.') : t('{n} requests went to an address nothing here declares. A module can do that; nothing can do it unlogged.', { n: undeclared }))
+      ? (undeclared === 1 ? t('1 request went to an address not on this list. A module can do that, but it is always logged.') : t('{n} requests went to addresses not on this list. A module can do that, but it is always logged.', { n: undeclared }))
       : t('Every request this process made went to an address declared above.'),
   };
 }

package/src/override.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 import { createHash, timingSafeEqual } from 'node:crypto';
 
 // How #3 CONTROL and #4 AIRLOCK are unlocked, as the person chose it in AJUSTES › Permissions.

package/src/ports.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // What is listening on this computer, so RIPLEY can look at it.
 //
 // A room that renders a project's files but cannot open the project's own dev server is half a

package/src/prices.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // What a turn would cost at the provider's API list price, for the CLIs that do not say it
 // themselves. Claude Code reports its own figure (`total_cost_usd`); Codex and Gemini report only
 // tokens, and OpenCode reports 0 when the model runs on a subscription. So the room prices those

package/src/privacy.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Privacy: terms that must never travel through a room. ERROR-001 in a real room
 // showed the channel: an agent's own configuration (organisation instructions,
 // the account it runs under) leaks into its reply, the reply enters the shared

package/src/quota-monitor.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 export class QuotaMonitor {
   #sources;
   #onReport;

package/src/quota-sources.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 import { execFile } from 'node:child_process';
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';

package/src/request-guard.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // The room listens on 127.0.0.1, which keeps other computers out but not other web pages: any
 // site open in this browser can send a request to 127.0.0.1:4317, and an uploaded module is code
 // MADRE runs with your permissions. Two checks, before any route, close that door.

package/src/review-ask.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Asking for a star or a review (2026-10-10): three times at most, and never again once answered.
 //
 // After twenty minutes of MADRE in use, and on the second and the seventh day after it was first

package/src/room/archivist.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // The archivist: every so often the cheapest allowed agent reads what nobody
 // has distilled and keeps the few notes worth remembering. Scheduling by count
 // or by quiet, one batch per run, a bench for whoever fails, a report to the

package/src/room/attachments.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Human uploads, stored under the room (never in the project). Registered
 // here so a message can reference them by id; the ledger lets a restarted
 // room rebuild the registry.

package/src/room/budget.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // The local token budget: a rolling window per agent (five hours, like the
 // providers' short windows), raw totals for the record, and the seeding of the
 // usage sentinel from the ledger on start.

package/src/room/context.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // The context an agent gets: the recent transcript verbatim and, when the
 // room is longer than that window, the older exchanges that match this
 // request, recalled from memory inside the same character budget.