@jossuealcala/madre 0.4.0 → 0.5.0

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

@@ -79,8 +79,20 @@ export async function verifyModuleText({ text, name = null, replace = true }) {
   try {
     const probe = join(scratch, name && /\.m?js$/.test(name) ? basename(name) : 'candidate.mjs');
     await writeFile(probe, text);
-    const module = checkExternal(await importModuleFile(probe), { replace });
-    return { id: module.id, name: module.name, vendor: module.vendor, version: module.version ?? null, summary: module.summary ?? '', updates: module.updates ?? null };
+    let module;
+    try {
+      module = checkExternal(await importModuleFile(probe), { replace });
+    } catch (error) {
+      // The one mistake that looks right and never works: MADRE's own modules import the SDK by
+      // relative path because they live inside the package, and anyone — an agent most of all —
+      // reading one of them copies that line. Here the file is alone in a scratch folder, so the
+      // import cannot resolve and node says only that it cannot find a file. Say what to do.
+      if (error?.code === 'ERR_MODULE_NOT_FOUND' || /Cannot find (module|package)/.test(error?.message ?? '')) {
+        throw new Error(`${error.message.split('\n')[0]} — a module imports nothing: MADRE loads it from a folder of its own to check it, where no package resolves. Export a plain object, or a function ({ defineModule }) => defineModule({ … }) and MADRE hands you the SDK.`);
+      }
+      throw error;
+    }
+    return { id: module.id, name: module.name, vendor: module.vendor, version: module.version ?? null, summary: module.summary ?? '', updates: module.updates ?? null, unknown: module.unknown ?? [] };
   } finally { await rm(scratch, { recursive: true, force: true, maxRetries: 6, retryDelay: 60 }); }
 }
 
@@ -95,7 +107,7 @@ export async function installModuleText({ text, name = null, scope = 'user', sta
   // Where it came from, so the same place can be asked for a newer one later.
   if (source) await writeFile(join(dir, `${module.id}.source.json`), JSON.stringify({ ...source, at: new Date().toISOString(), version: module.version ?? null }, null, 2)).catch(() => {});
   await loadExternalModules({ stateRoot, projectRoot });
-  return { id: module.id, name: module.name, version: module.version ?? null, file: target, origin: scope === 'project' ? 'project' : 'user', replaced };
+  return { id: module.id, name: module.name, version: module.version ?? null, file: target, origin: scope === 'project' ? 'project' : 'user', replaced, unknown: module.unknown ?? [] };
 }
 
 // The same thing from a file already on this computer. `source` must be inside the project or the
@@ -122,9 +134,15 @@ export async function removeExternalModule({ id, stateRoot, projectRoot }) {
   const module = MODULES.find((known) => known.id === id);
   if (!module) throw new Error(`No module "${id}".`);
   if (!module.external) throw new Error(`${module.name} ships with MADRE and cannot be removed; switch it off instead.`);
-  await unlink(module.file).catch(() => {});
+  // The origin record goes first: if it cannot be removed, the executable module file remains
+  // installed rather than leaving a live registry entry whose file has already disappeared.
+  const files = [...new Set([module.file.replace(/\.(?:mjs|js)$/, '.source.json'), module.file])];
+  const removedFiles = [];
+  for (const file of files) {
+    try { await unlink(file); removedFiles.push(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
   await loadExternalModules({ stateRoot, projectRoot });
-  return { id, name: module.name, file: module.file };
+  return { id, name: module.name, file: module.file, removedFiles };
 }
 
 export const moduleById = (id) => MODULES.find((module) => module.id === id) ?? null;

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/modules/sdk.mjs

@@ -51,6 +51,19 @@ export function dependencies(runs) {
   return list.filter((dep) => dep && dep.name).map((dep) => ({ name: String(dep.name), version: dep.version ?? null, target: dep.target ?? null }));
 }
 
+// Every field this contract answers to. Thirty-four of them and all but two optional, which is
+// generous until you misspell one: `sumary` used to install without a word and leave a card with
+// an empty summary. A key MADRE does not know is not fatal — a module written for a newer MADRE
+// may carry fields this one has not learned yet — so it is said out loud instead of refused.
+export const MODULE_FIELDS = new Set([
+  'id', 'kind', 'name', 'vendor', 'package', 'version', 'tracks', 'updates', 'summary', 'creates',
+  'requires', 'models', 'commands', 'card', 'configKey', 'settings', 'controls', 'routes',
+  'conditions', 'slash', 'status', 'preflight', 'detect', 'confirm', 'installCommand',
+  'updatePlan', 'toolsForTurn', 'toggle', 'onToggle', 'onSettings', 'onEvent', 'toggledEvent',
+  'toggledBody', 'describe',
+]);
+export const unknownFields = (spec) => Object.keys(spec ?? {}).filter((key) => !MODULE_FIELDS.has(key));
+
 export function defineModule(spec) {
   if (!spec?.id || !/^[a-z][a-z0-9-]*$/.test(spec.id)) throw new Error(`Module id must be kebab-case: ${spec?.id}`);
   if (!spec.name) throw new Error(`Module ${spec.id} needs a name.`);
@@ -59,6 +72,8 @@ export function defineModule(spec) {
   const defaults = { ...(kind === 'builtin' ? { enabled: false } : {}), ...(spec.settings ?? {}) };
   const base = {
     id: spec.id, kind, name: spec.name, vendor: spec.vendor ?? 'MADRE', package: spec.package ?? null, version: spec.version ?? null,
+    // Keys this contract does not answer to. Carried so whoever installs the module is told.
+    unknown: unknownFields(spec),
     // What this module's version follows, when it is not its own: { name, npm } or { name, github }.
     // MADRE reads the version from there and looks for a newer one on its own, once a day.
     tracks: spec.tracks ? { name: spec.tracks.name ?? spec.tracks.npm ?? spec.tracks.github ?? null, npm: spec.tracks.npm ?? null, github: spec.tracks.github ?? null } : null,

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 = [
@@ -264,7 +269,7 @@ export class OutboundLog {
 export function outboundView({ log = null, state = {}, agents = [] } = {}) {
   const counts = log?.counts() ?? {};
   const vendors = { codex: 'OpenAI', claude: 'Anthropic', gemini: 'Google', opencode: 'the provider OpenCode is signed in to' };
-  const crew = agents.filter((agent) => agent.detected && !agent.local).map((agent) => `@${agent.id} → ${vendors[agent.id] ?? 'its own provider'}`);
+  const crew = agents.filter((agent) => agent.detected && !agent.local).map((agent) => `@${agent.id} → ${agent.route?.destination ?? vendors[agent.id] ?? 'its own provider'}`);
   const destinations = DESTINATIONS.map((one) => ({
     id: one.id,
     to: one.id === 'crew' && crew.length ? crew.join(' · ') : one.to,

package/src/room.mjs

@@ -945,6 +945,18 @@ export class Room {
       await this.#emit('message.failed', { messageId, target: targetId, planId, error: `${agent.label} was detected, but its MADRE adapter is not enabled yet.` });
       return null;
     }
+    if (agent.route?.custom && !agent.route.allowed) {
+      const destination = agent.route.host ?? 'an unrecognised host';
+      const source = agent.route.source ?? 'a custom endpoint setting';
+      const official = agent.id === 'codex' ? 'OpenAI' : agent.id === 'claude' ? 'Anthropic' : 'the agent\'s official service';
+      await this.#emit('message.failed', {
+        messageId,
+        target: targetId,
+        planId,
+        error: `MADRE blocked @${agent.id} before sending the briefing: ${source} points to ${destination}, not ${official}. Remove that override to use the official service, or set PULSE_ALLOW_CUSTOM_AGENT_ENDPOINTS=${agent.id} only if you trust that endpoint.`,
+      });
+      return null;
+    }
 
     const priorEvents = await this.#store.readAll();
     // @madre never reads its own canned replies back: a small model would echo them.

package/src/runtime-detection.mjs

@@ -38,6 +38,55 @@ const definitions = [
   },
 ];
 
+const OFFICIAL_DESTINATIONS = {
+  codex: { label: 'OpenAI', hosts: ['api.openai.com'], variable: 'OPENAI_BASE_URL' },
+  claude: { label: 'Anthropic', hosts: ['api.anthropic.com'], variable: 'ANTHROPIC_BASE_URL' },
+};
+
+const enabled = (value) => /^(1|true|yes)$/i.test(String(value ?? '').trim());
+
+function customRoutesAllowed(agentId, env) {
+  const raw = String(env.PULSE_ALLOW_CUSTOM_AGENT_ENDPOINTS ?? '').trim().toLowerCase();
+  if (/^(1|true|all)$/.test(raw)) return true;
+  return raw.split(',').map((item) => item.trim()).includes(agentId);
+}
+
+function routeHost(value) {
+  try { return new URL(value).hostname.toLowerCase(); } catch { return null; }
+}
+
+// A CLI owns its network connection, but MADRE owns the document handed to that CLI. Name the
+// actual destination without ever returning a credential, path or query string. Unknown base URLs
+// are held at the door until the human explicitly trusts that agent's endpoint.
+export function agentRouteFromEnvironment(agentId, env = process.env) {
+  if (agentId === 'claude' && enabled(env.CLAUDE_CODE_USE_BEDROCK)) {
+    return { kind: 'provider', destination: 'Amazon Bedrock', source: 'CLAUDE_CODE_USE_BEDROCK', host: null, custom: false, allowed: true };
+  }
+  if (agentId === 'claude' && enabled(env.CLAUDE_CODE_USE_VERTEX)) {
+    return { kind: 'provider', destination: 'Google Vertex AI', source: 'CLAUDE_CODE_USE_VERTEX', host: null, custom: false, allowed: true };
+  }
+  if (agentId === 'claude' && enabled(env.CLAUDE_CODE_USE_FOUNDRY)) {
+    return { kind: 'provider', destination: 'Microsoft Foundry', source: 'CLAUDE_CODE_USE_FOUNDRY', host: null, custom: false, allowed: true };
+  }
+
+  const official = OFFICIAL_DESTINATIONS[agentId];
+  if (!official) return null;
+  const raw = String(env[official.variable] ?? '').trim();
+  if (!raw) return { kind: 'official', destination: official.label, source: null, host: null, custom: false, allowed: true };
+  const host = routeHost(raw);
+  const isOfficial = Boolean(host && official.hosts.some((candidate) => host === candidate || host.endsWith(`.${candidate}`)));
+  if (isOfficial) return { kind: 'official', destination: official.label, source: official.variable, host, custom: false, allowed: true };
+  const allowed = customRoutesAllowed(agentId, env);
+  return {
+    kind: 'custom',
+    destination: host ? `custom endpoint · ${host}` : 'custom endpoint',
+    source: official.variable,
+    host,
+    custom: true,
+    allowed,
+  };
+}
+
 async function executable(path) {
   try {
     await access(path, constants.X_OK);
@@ -99,6 +148,7 @@ export async function detectAgents({ env = process.env } = {}) {
       adapter: definition.adapter ?? null,
       path,
       version: path ? await readVersion(path, definition.versionArgs) : null,
+      route: agentRouteFromEnvironment(definition.id, env),
     };
   }));
 }

package/src/sentinel-errors.mjs

@@ -10,6 +10,12 @@
 import { createHash } from 'node:crypto';
 import { homedir, platform, arch, release } from 'node:os';
 import { diagnose } from '../public/troubleshooting.js';
+import { language } from './i18n.mjs';
+
+// The product's own house. The collector lives under it too, so the line a human reads in the
+// outbound log names the product instead of a personal endpoint on someone's cloud account.
+export const HOME_SITE = 'https://madre.run';
+export const REPORT_FORM = { es: `${HOME_SITE}/reportar`, en: `${HOME_SITE}/report` };
 
 export const REPORT_WINDOW_MS = 24 * 3600 * 1000;
 const MAX_ERROR_CHARS = 4000;
@@ -71,7 +77,7 @@ export class ErrorSentinel {
     this.#save = save;
   }
 
-  settings() { return { ...this.#settings, canSend: Boolean(this.#settings.reportUrl), repo: repoFromPackage(this.#pkg) }; }
+  settings() { return { ...this.#settings, canSend: Boolean(this.#settings.reportUrl), repo: repoFromPackage(this.#pkg), home: HOME_SITE }; }
   async setSettings(patch = {}) {
     if (typeof patch.autoReport === 'boolean') this.#settings.autoReport = patch.autoReport;
     if (typeof patch.reportUrl === 'string') this.#settings.reportUrl = patch.reportUrl.trim();
@@ -174,6 +180,18 @@ export class ErrorSentinel {
     return `https://github.com/${repo}/issues/new?${new URLSearchParams({ title, body, labels: 'sentinel' })}`;
   }
 
+  // Where a human goes to say something. GitHub is the better home for a report — it is
+  // searchable, it deduplicates, and the answer helps whoever hits it next — but it asks for an
+  // account first, and somebody who arrived from a post in Spanish will not make one to say "it
+  // does not detect Codex". They get the form; the other road stays one click away, both ways.
+  formUrl({ about = '' } = {}) {
+    const base = REPORT_FORM[language()] ?? REPORT_FORM.en;
+    const env = this.environment();
+    const query = new URLSearchParams({ v: env.madre, node: env.node, os: env.platform });
+    if (about) query.set('about', about.slice(0, 120));
+    return `${base}?${query}`;
+  }
+
   feedbackUrl({ about = '' } = {}) {
     const repo = repoFromPackage(this.#pkg);
     if (!repo) return null;

package/src/server.mjs

@@ -18,7 +18,7 @@ import { moduleById, describeModules, findModuleRoute, toolsForTurn as modulesTo
 import { madreAgent, madreInvoker, MADRE_AGENT_ID, MADRE_ADAPTER } from './adapters/madre.mjs';
 import { exportDataset, readiness as datasetReadiness } from './dataset.mjs';
 import { OutboundLog, outboundView, DEFAULT_REPORT_URL } from './outbound.mjs';
-import { setLanguage as setRoomLanguage, t } from './i18n.mjs';
+import { language as roomLanguage, setLanguage as setRoomLanguage, t } from './i18n.mjs';
 
 const PACKAGE = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8').catch(() => '{}'));
 let crashHandlersInstalled = false;
@@ -47,6 +47,9 @@ import { applyKey, keyPlanFor } from './credentials.mjs';
 import { loadConfig as readConfig, updateConfig } from './config.mjs';
 import { Privacy, normalizeTerms, privacySettings } from './privacy.mjs';
 import { checkForUpdate, detectInstall, updateCommand, releaseUrl, applyCommand } from './updates.mjs';
+
+// Where a person reads the module contract, in the language the room is speaking.
+const SDK_PAGE = { es: 'https://madre.run/sdk/', en: 'https://madre.run/en/sdk/' };
 import { moduleUpdate } from './modules/updates.mjs';
 import { adoptStrays, chatIndex, chatLedger, createChat, deleteChat, isChatId, listChats, openChat as openChatIndex, projectFloor, renameChat, touchChat, MAIN_CHAT } from './chats.mjs';
 import { spawn } from 'node:child_process';
@@ -193,7 +196,7 @@ export async function createPulseServer({
   const install = detectInstall({ projectRoot: canonicalProjectRoot });
   async function versionView({ force = false } = {}) {
     const check = await checkForUpdate({ name: PACKAGE.name, current: PACKAGE.version, cacheFile: join(root, 'updates.json'), fetchImpl: reportFetch, enabled: updatesEnabled(), force });
-    return { project: canonicalProjectRoot, ...check, name: PACKAGE.name, install, command: updateCommand(install, PACKAGE.name, check.latest ?? 'latest'), release: check.latest ? releaseUrl(PACKAGE.repository, check.latest) : null, envWins: process.env.PULSE_UPDATE_CHECK !== undefined };
+    return { project: canonicalProjectRoot, ...check, name: PACKAGE.name, install, command: updateCommand(install, PACKAGE.name, check.latest ?? 'latest'), release: check.latest ? releaseUrl(PACKAGE.repository, check.latest, roomLanguage()) : null, envWins: process.env.PULSE_UPDATE_CHECK !== undefined };
   }
   // Keeping the day's cache warm. MODULES is served from what is already on disk, so the looking
   // happens after the screen is answered, never in front of it: at most once an hour per room,
@@ -250,7 +253,7 @@ export async function createPulseServer({
     else if (!fifth.ready && index >= 0) { agents.splice(index, 1); changed = true; }
     if (room) {
       room.setInvoker(MADRE_ADAPTER, fifth.ready ? madreInvoker({ memory, ollama: () => ({ ...ollama, chatModel: ollama.madreModel ?? ollama.chatModel }), fetchImpl: reportFetch }) : null);
-      if (changed) await room.record('agents.updated', { agents: agents.map((agent) => ({ id: agent.id, label: agent.label, detected: agent.detected, ready: agent.ready, version: agent.version, local: Boolean(agent.local) })), removed: fifth.ready ? [] : [MADRE_AGENT_ID], reason: fifth.ready ? `@madre is in the room · ${fifth.version}` : '@madre left the room: Ollama has no chat model running' });
+      if (changed) await room.record('agents.updated', { agents: agents.map((agent) => ({ id: agent.id, label: agent.label, detected: agent.detected, ready: agent.ready, version: agent.version, local: Boolean(agent.local), route: agent.route ?? null })), removed: fifth.ready ? [] : [MADRE_AGENT_ID], reason: fifth.ready ? `@madre is in the room · ${fifth.version}` : '@madre left the room: Ollama has no chat model running' });
       // That a local model is running is not the same as it being of use on this project, and
       // the second thing is the one a person needs told. Said once per model, in the room, with
       // the one button that settles it — the crew line above fires only when the crew CHANGES,
@@ -465,7 +468,7 @@ export async function createPulseServer({
       const index = agents.findIndex((item) => item.id === next.id);
       if (index === -1) { agents.push(next); changed = true; continue; }
       const before = agents[index];
-      if (before.detected !== next.detected || before.ready !== next.ready || before.version !== next.version || before.path !== next.path) {
+      if (before.detected !== next.detected || before.ready !== next.ready || before.version !== next.version || before.path !== next.path || JSON.stringify(before.route ?? null) !== JSON.stringify(next.route ?? null)) {
         agents[index] = { ...before, ...next };
         changed = true;
       }
@@ -473,7 +476,7 @@ export async function createPulseServer({
     await refreshSessions();
     if (changed && announce) {
       await room.record('agents.updated', {
-        agents: agents.map((agent) => ({ id: agent.id, label: agent.label, detected: agent.detected, ready: agent.ready, version: agent.version, local: Boolean(agent.local) })),
+        agents: agents.map((agent) => ({ id: agent.id, label: agent.label, detected: agent.detected, ready: agent.ready, version: agent.version, local: Boolean(agent.local), route: agent.route ?? null })),
         removed: [],
         reason: 'the room looked again for the agents on this computer',
       });
@@ -846,7 +849,7 @@ export async function createPulseServer({
         response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
         return response.end(html);
       }
-      if (request.method === 'GET' && ['/app.js', '/brands.js', '/troubleshooting.js', '/inquiry.js', '/i18n.js', '/es.js', '/resay.js'].includes(url.pathname)) {
+      if (request.method === 'GET' && ['/app.js', '/brands.js', '/troubleshooting.js', '/inquiry.js', '/i18n.js', '/es.js', '/resay.js', '/syntax.js'].includes(url.pathname)) {
         const js = await readFile(join(publicDirectory, url.pathname.slice(1)));
         response.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' });
         return response.end(js);
@@ -860,8 +863,11 @@ export async function createPulseServer({
         return sendJson(response, 200, {
           projectRoot,
           platform: process.platform,
-          // What language this machine set MADRE to, for a browser that has never chosen.
-          language: (await readConfig(root)).language === 'en' ? 'en' : 'es',
+          // What language this machine set MADRE to, for a browser that has never chosen. It is
+          // the language the room is SPEAKING, not the one written in the file: PULSE_LANGUAGE
+          // wins over the config here as it does everywhere else, and reading the file again
+          // would hand the page a different answer from the one the server itself is using.
+          language: roomLanguage(),
           // Which conversation this page is looking at, and the others it could open.
           chats: await listChats(roomDir),
           agents: agents.map((agent) => ({ ...agent, login: loginPlanFor(agent), install: installPlanFor(agent), key: keyPlanFor(agent.id), ...(accountNoteFor(agent.id) ?? {}) })),
@@ -980,7 +986,7 @@ export async function createPulseServer({
       const designationOk = (given) => typeof given === 'string' && given.trim().toLowerCase() === basename(canonicalProjectRoot).toLowerCase();
       // Sentinel: reports, settings, the manual road (a prefilled issue) and the automatic one.
       if (request.method === 'GET' && url.pathname === '/api/sentinel') {
-        return sendJson(response, 200, { reports: sentinel.reports(), settings: sentinel.settings(), environment: sentinel.environment(), feedbackUrl: sentinel.feedbackUrl() });
+        return sendJson(response, 200, { reports: sentinel.reports(), settings: sentinel.settings(), environment: sentinel.environment(), feedbackUrl: sentinel.feedbackUrl(), formUrl: sentinel.formUrl() });
       }
       if (request.method === 'POST' && url.pathname === '/api/sentinel/settings') {
         const patch = await body(request).catch(() => ({}));
@@ -991,8 +997,13 @@ export async function createPulseServer({
       const sentinelMatch = url.pathname.match(/^\/api\/sentinel\/([a-f0-9]{10})\/(issue|send)$/);
       if (sentinelMatch && request.method === (sentinelMatch[2] === 'issue' ? 'GET' : 'POST')) {
         if (sentinelMatch[2] === 'issue') {
-          const issue = sentinel.issueUrl(sentinelMatch[1]);
-          return issue ? sendJson(response, 200, { url: issue }) : sendJson(response, 404, { error: t('No such report, or no repository to file it in.') });
+          // Both roads, always: the issue for whoever has an account, the form for whoever does
+          // not. Nobody should hit a login wall while holding a bug report. A report that does
+          // not exist still gets neither: the form does not need the report to be built, so it
+          // would otherwise hand out a link for nothing.
+          const known = sentinel.reports().some((one) => one.id === sentinelMatch[1]);
+          const issue = known ? sentinel.issueUrl(sentinelMatch[1]) : null;
+          return known ? sendJson(response, 200, { url: issue, form: sentinel.formUrl({ about: sentinelMatch[1] }) }) : sendJson(response, 404, { error: t('No such report, or no repository to file it in.') });
         }
         const outcome = await sentinel.send(sentinelMatch[1]);
         return sendJson(response, outcome.ok ? 200 : (outcome.status === 404 || outcome.status === 412 ? outcome.status : 502), outcome);
@@ -1466,7 +1477,7 @@ export async function createPulseServer({
       if (request.method === 'GET' && url.pathname === '/api/extensions') {
         const extensions = await describeModules(await moduleContext());
         void warmModuleUpdates(extensions);
-        return sendJson(response, 200, { installing, extensions, failures: loadFailures, folders: moduleFolders({ stateRoot: root, projectRoot: canonicalProjectRoot }), sdk: 'https://github.com/jossuealcacao-exe/madre/blob/main/docs/SDK.md' });
+        return sendJson(response, 200, { installing, extensions, failures: loadFailures, folders: moduleFolders({ stateRoot: root, projectRoot: canonicalProjectRoot }), sdk: SDK_PAGE[roomLanguage()] ?? SDK_PAGE.es });
       }
       // The human installs a module file an agent wrote (or they did): checked first, then copied into the chosen folder.
       if (request.method === 'POST' && url.pathname === '/api/extensions/install-file') {

package/src/updates.mjs

@@ -51,7 +51,15 @@ export function applyCommand({ install, name, version, port, projectRoot }) {
   }
 }
 
-export function releaseUrl(repository, version) {
+// Where a person reads what a version brought. The product's own house, in the language the room
+// is speaking — a release page on a code host is written for people who already work there, and
+// whoever pressed this button only wanted to know what changed. The repository stays the fallback
+// for a build with no house to point at.
+export const CHANGES_PAGE = { es: 'https://madre.run/cambios/', en: 'https://madre.run/en/changelog/' };
+
+export function releaseUrl(repository, version, language = 'es') {
+  const page = CHANGES_PAGE[language] ?? CHANGES_PAGE.es;
+  if (page) return version ? `${page}#v${version}` : page;
   const url = String(repository?.url ?? repository ?? '').replace(/^git\+/, '').replace(/\.git$/, '');
   return url ? `${url}/releases/tag/v${version}` : null;
 }