@jossuealcala/madre 0.3.3 → 0.4.1

package/src/modules/ahp.mjs

@@ -2,9 +2,10 @@
 // command. Verified project state, checkpoints and handoffs in .ahp/.
 
 import { join, resolve } from 'node:path';
+import { t } from '../i18n.mjs';
 import { realpath } from 'node:fs/promises';
 import { defineModule } from './sdk.mjs';
-import { readJson, gitToplevel, findOnPath } from './helpers.mjs';
+import { readJson, gitToplevel, findOnPath, packageVersion } from './helpers.mjs';
 
 // AHP+ platform names for the agents MADRE knows about. Gemini has no AHP+
 // adapter yet, so it is simply not requested.
@@ -14,14 +15,14 @@ const VERSION = '1.4.1';
 
 async function detect(projectRoot) {
   const manifest = await readJson(join(projectRoot, '.ahp', 'manifest.json'));
-  if (!manifest) return { installed: false };
-  const pinned = await readJson(join(projectRoot, 'node_modules', '@jossuealcala', 'ahp-plus', 'package.json'));
+  if (!manifest) return { installed: false, detail: t('not in this project') };
+  const pinned = await packageVersion(PACKAGE, { projectRoot });
   return {
     installed: true,
-    version: pinned?.version ?? null,
+    version: pinned ?? null,
     protocolVersion: manifest.protocol_version ?? null,
     projectId: manifest.project_id ?? null,
-    detail: [pinned?.version ? `cli ${pinned.version}` : null, manifest.protocol_version ? `protocol ${manifest.protocol_version}` : null].filter(Boolean).join(' · '),
+    detail: [pinned ? `cli ${pinned}` : null, manifest.protocol_version ? `protocol ${manifest.protocol_version}` : null].filter(Boolean).join(' · '),
   };
 }
 
@@ -52,13 +53,14 @@ export default defineModule({
   name: 'AHP+',
   vendor: 'Agent Handoff Protocol Plus',
   package: PACKAGE,
-  version: VERSION,
+  tracks: { name: PACKAGE, npm: PACKAGE },
   summary: 'Verified project state, checkpoints and handoffs between AI sessions, stored in .ahp/ next to your code.',
+  requires: ['the project is a git repository', 'npx on the PATH of the terminal MADRE was started from'],
   creates: ['.ahp/ with manifest, sessions, handoffs and evidence', 'a project-local pin of @jossuealcala/ahp-plus', 'IDE adapter files for the detected agents'],
   detect, preflight, installCommand,
   async status(ctx) {
     const status = await detect(ctx.projectRoot);
     const plan = installCommand({ agents: ctx.agents });
-    return { status, preflight: await preflight(ctx.projectRoot), install: { display: plan.display, platforms: plan.platforms } };
+    return { status, runs: [{ name: PACKAGE, version: await packageVersion(PACKAGE, { projectRoot: ctx.projectRoot }), target: VERSION }], preflight: await preflight(ctx.projectRoot), install: { display: plan.display, platforms: plan.platforms } };
   },
 });

package/src/modules/ash.mjs

@@ -0,0 +1,36 @@
+// Ash: MADRE's token economy.
+//
+// It used to be a text compressor that rewrote the human's message before sending it. That was
+// retired: it altered the one thing nobody asked it to touch, it was lossy, and measured against
+// a real turn it saved a fifth of one per cent. Everything it claimed to do is now done without
+// touching a word anyone wrote.
+//
+// Most of the economy needs no switch and is always on, because none of it loses anything: the
+// briefing carries only the blocks a turn can use, what never changes is read first so a CLI can
+// take it from its own cache, the transcript window holds still instead of sliding, and every
+// turn is weighed against what it was actually charged.
+//
+// What is left to decide is the one thing that changes how an agent answers rather than what it
+// is asked: whether to ask for compact prose. Output is the dearer half of a bill, so this is
+// the switch worth having, and it is the human's to make.
+
+import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.mjs';
+
+export default defineModule({
+  id: 'ash',
+  configKey: 'ash',
+  name: 'Ash',
+  vendor: 'MADRE',
+  version: '1.0.0',
+  summary: 'Asks every agent for compact prose. The rest of the economy is always on: the briefing carries only what a turn can use, what never changes is read first so a cache can match it, and the transcript holds still instead of sliding.',
+  creates: ['nothing in the project', 'a switch in ~/.pulse/config.json'],
+  card: 'ash',
+  async status(ctx) {
+    return {
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? t('on · agents answer in compact prose') : t('off · agents answer at their own length') },
+      install: { display: ctx.settings.enabled ? 'stop asking for compact replies' : 'ask every agent for compact replies', platforms: [] },
+    };
+  },
+  async onToggle(ctx, enabled) { ctx.room.setAsh(enabled); return null; },
+});

package/src/modules/git-pulse.mjs

@@ -2,21 +2,23 @@
 // Nothing to switch: it is on wherever the project is a git repository.
 
 import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.mjs';
 import { gitToplevel } from './helpers.mjs';
 
 export default defineModule({
   id: 'git-pulse',
   name: 'Git Pulse',
   vendor: 'MADRE',
-  summary: 'Type /git in the composer to bring the repository\'s branch, uncommitted changes, recent commits or diff stats into the room as a shared fact card, without spending an agent turn. /git commit and /git push are your own hand on the repository: a commit is local, a push shows what would leave and only goes with /git push confirm.',
-  creates: ['nothing by itself: the read commands are read-only', 'a commit or a push only when you type /git commit or /git push confirm'],
+  version: '1.0.0',
+  summary: 'Brings the repository into the room: /git posts the branch, the uncommitted changes, the recent commits or the diff stats as a shared fact card, without spending an agent turn.',
+  creates: ['nothing by itself \u00b7 the read commands only read', 'a local commit only when you type /git commit', 'a push only when you type /git push confirm, after it shows what would leave'],
   requires: ['the project is a git repository'],
   commands: ['/git status', '/git log [n]', '/git diff', '/git branches', '/git commit "message"', '/git push [confirm]'],
   card: 'fixed',
   async status(ctx) {
     const isRepo = await gitToplevel(ctx.projectRoot);
     return {
-      status: { installed: Boolean(isRepo), detail: isRepo ? 'on · project is a git repository' : 'not a git repository' },
+      status: { installed: Boolean(isRepo), detail: isRepo ? t('on · project is a git repository') : t('not a git repository') },
       preflight: isRepo ? { ok: true, problems: [] } : { ok: false, problems: ['Run `git init` in the project to use /git.'] },
       install: { display: '/git in the composer', platforms: [] },
       fixed: true,

package/src/modules/helpers.mjs

@@ -28,3 +28,34 @@ export async function findOnPath(name, envPath = process.env.PATH ?? '') {
   }
   return null;
 }
+
+// The version of an npm package that is actually on this machine, found by reading its
+// package.json: up the node_modules chain from the project first, then npm's global root.
+// Nothing is executed. Asking a package for its own --version through npx is not a test of
+// anything: when the package is not installed at all, npx answers with npm's version and exits
+// cleanly, which is how PLAYWRIGHT came to report a browser server that was never there.
+let globalRoot;
+async function npmGlobalRoot(env = process.env) {
+  if (globalRoot !== undefined) return globalRoot;
+  try { const { stdout } = await execFileAsync('npm', ['root', '-g'], { env, timeout: 10000 }); globalRoot = stdout.trim() || null; }
+  catch { globalRoot = null; }
+  return globalRoot;
+}
+
+export async function packageVersion(name, { projectRoot = process.cwd(), env = process.env } = {}) {
+  const parts = name.split('/');
+  let directory = projectRoot;
+  for (let depth = 0; depth < 24; depth += 1) {
+    const found = await readJson(join(directory, 'node_modules', ...parts, 'package.json'));
+    if (found?.version) return found.version;
+    const parent = join(directory, '..');
+    if (parent === directory) break;
+    directory = parent;
+  }
+  const root = await npmGlobalRoot(env);
+  if (root) {
+    const found = await readJson(join(root, ...parts, 'package.json'));
+    if (found?.version) return found.version;
+  }
+  return null;
+}

package/src/modules/image-studio.mjs

@@ -2,6 +2,7 @@
 // the CLIs that cannot draw natively. A switch and a model in config.json.
 
 import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.mjs';
 
 const MODELS = ['gemini-2.5-flash-image', 'gemini-3.1-flash-image', 'gemini-3-pro-image'];
 
@@ -10,18 +11,23 @@ export default defineModule({
   configKey: 'imageStudio',
   name: 'Image Studio',
   vendor: 'MADRE · Gemini API',
-  summary: 'Gives Gemini CLI, Claude Code and OpenCode an image-generation tool through a MADRE-owned MCP server on the Gemini API image models, using your own Gemini key and credits. Attached only inside a creation lease with the image scope on.',
-  creates: ['nothing in the project: images land in the lease directory like any artifact', 'an "image-studio" entry in ~/.pulse/config.json', 'an MCP server process per turn, started and stopped by the room'],
-  requires: ['a Gemini API key with credits (the key the Gemini CLI stores, or GEMINI_API_KEY)'],
+  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'],
+  // 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',
+  controls: [{ key: 'model', label: 'MODEL', type: 'select', options: MODELS, note: 'The Gemini image model Image Studio draws with. It bills against your own key.' }],
+  // Changing the model while it is on has to reach the running room, not just the file.
+  async onSettings(ctx, settings) { if (settings.enabled) ctx.services.setImageModule({ enabled: true, model: settings.model }); },
   async status(ctx) {
     const key = await ctx.services.imageKey();
     const model = ctx.settings.model ?? MODELS[0];
     return {
       model,
-      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? `on · ${model}${key ? '' : ' · no Gemini key found'}` : key ? 'key found' : 'no Gemini key found' },
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? `${t('on')} · ${model}${key ? '' : t(' · no Gemini key found')}` : key ? t('key found') : t('no Gemini key found') },
       preflight: key ? { ok: true, problems: [] } : { ok: false, problems: ['No Gemini API key: sign in with the Gemini CLI (/auth → API key) or set GEMINI_API_KEY. Image models bill against that key.'] },
       install: { display: ctx.settings.enabled ? 'disable Image Studio' : 'enable Image Studio (config.json)', platforms: ['gemini', 'claude', 'opencode'] },
     };

package/src/modules/index.mjs

@@ -1,21 +1,144 @@
-// The registry. Order is the order MODULES shows.
+// The registry. Order is the order MODULES shows. MADRE's own modules first; then the
+// human's, loaded from ~/.pulse/modules/*.mjs (every project) and <project>/.madre/modules/*.mjs
+// (this project). An external module is a file whose default export is a plain spec object
+// (defineModule is applied here), a module already built with defineModule, or a function
+// receiving { defineModule } and returning either. Agents cannot write those folders: .madre/
+// is a forbidden zone, and ~/.pulse lives outside every project.
+import { readdir, readFile, writeFile, mkdir, unlink, mkdtemp, rm, access } from 'node:fs/promises';
+import { translate } from '../i18n.mjs';
+import { join, basename, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import ahp from './ahp.mjs';
 import imageStudio from './image-studio.mjs';
 import gitPulse from './git-pulse.mjs';
-import ashcode from './ashcode.mjs';
+import ash from './ash.mjs';
 import ripley from './ripley.mjs';
 import ollama from './ollama.mjs';
 import playwright from './playwright.mjs';
-import { matchRoute } from './sdk.mjs';
+import { defineModule, matchRoute } from './sdk.mjs';
 
-export const MODULES = [ahp, imageStudio, gitPulse, ashcode, ripley, ollama, playwright];
-// Every tool server the modules hand to one turn, flattened; a module that fails hands nothing.
-export async function toolsForTurn(ctx, turn) {
-  const lists = await Promise.all(MODULES.filter((module) => module.toolsForTurn).map((module) => module.toolsForTurn(ctx, turn)));
-  return lists.flat().filter((server) => server && server.name && server.command);
+export const MODULES = [ahp, imageStudio, gitPulse, ash, ripley, ollama, playwright];
+export const BUILTIN_IDS = new Set(MODULES.map((module) => module.id));
+export const loadFailures = [];   // { file, error } for MODULES to show
+export const moduleFolders = ({ stateRoot, projectRoot }) => ({ user: join(stateRoot, 'modules'), project: join(projectRoot, '.madre', 'modules') });
+// Where the SDK guide and the example live in this installation, for agents who build modules.
+export const sdkPaths = () => ({ guide: fileURLToPath(new URL('../../docs/SDK.md', import.meta.url)), example: fileURLToPath(new URL('../../docs/sdk/hello-module.mjs', import.meta.url)) });
+// A file an agent wrote that means "install me as a module": <id>.module.mjs.
+export const isModuleFile = (path) => /\.module\.mjs$/.test(String(path ?? ''));
+
+// The rules an outside module must keep so it cannot reach MADRE's core: its own id, and its
+// routes under /api/x/<id>/ only, never MADRE's own paths.
+function checkExternal(module, { replace = false } = {}) {
+  const taken = MODULES.find((known) => known.id === module.id);
+  // A module that ships with MADRE can never be shadowed. One of the human's own can be
+  // replaced, because that is what installing a newer copy of it is.
+  if (taken && (!replace || !taken.external)) throw new Error(`the id "${module.id}" is already taken`);
+  for (const route of module.routes ?? []) {
+    const path = typeof route.path === 'string' ? route.path : route.path?.source ?? '';
+    if (!path.startsWith(`/api/x/${module.id}/`) && !path.startsWith(`\\/api\\/x\\/${module.id}\\/`)) throw new Error(`route ${path} must live under /api/x/${module.id}/`);
+  }
+  return module;
+}
+
+// Loads one file as a module, throwing a readable error when it is not one.
+async function importModuleFile(file) {
+  const loaded = await import(`${pathToFileURL(file).href}?t=${Date.now()}`);
+  let spec = loaded.default ?? loaded.module ?? null;
+  if (typeof spec === 'function') spec = await spec({ defineModule });
+  if (!spec || typeof spec !== 'object') throw new Error('the default export must be a module spec object');
+  return typeof spec.describe === 'function' ? spec : defineModule(spec);
+}
+
+export async function loadExternalModules({ stateRoot, projectRoot }) {
+  for (let index = MODULES.length - 1; index >= 0; index -= 1) if (MODULES[index].external) MODULES.splice(index, 1);
+  loadFailures.length = 0;
+  const folders = moduleFolders({ stateRoot, projectRoot });
+  for (const [origin, dir] of Object.entries(folders)) {
+    let files = [];
+    try { files = (await readdir(dir)).filter((name) => /\.(mjs|js)$/.test(name) && !name.startsWith('.')).sort(); } catch { continue; }
+    for (const name of files) {
+      const file = join(dir, name);
+      try {
+        const module = checkExternal(await importModuleFile(file));
+        MODULES.push(Object.freeze({ ...module, external: true, origin, file }));
+      } catch (error) {
+        loadFailures.push({ file, origin, error: error.message });
+      }
+    }
+  }
+  return { loaded: MODULES.filter((module) => module.external), failures: [...loadFailures], folders };
+}
+
+// The one door every module comes through, whoever wrote it and wherever the text came from: it
+// is written to a scratch copy, imported there and checked against the house rules. A module runs
+// inside MADRE with the human's own permissions, so the check is the point. Checking installs
+// nothing and touches no registry — asking what a file is must never change what is loaded.
+export async function verifyModuleText({ text, name = null, replace = true }) {
+  const scratch = await mkdtemp(join(tmpdir(), 'madre-module-check-'));
+  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 };
+  } finally { await rm(scratch, { recursive: true, force: true, maxRetries: 6, retryDelay: 60 }); }
+}
+
+export async function installModuleText({ text, name = null, scope = 'user', stateRoot, projectRoot, source = null, replace = true }) {
+  const module = await verifyModuleText({ text, name, replace });
+  const replaced = Boolean(MODULES.find((known) => known.id === module.id)?.external);
+  const folders = moduleFolders({ stateRoot, projectRoot });
+  const dir = folders[scope === 'project' ? 'project' : 'user'];
+  await mkdir(dir, { recursive: true });
+  const target = join(dir, `${module.id}.mjs`);
+  await writeFile(target, text);
+  // 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 };
 }
+
+// The same thing from a file already on this computer. `source` must be inside the project or the
+// room folder; agents never reach the module folders themselves.
+export async function installModuleFile({ source, scope = 'user', stateRoot, projectRoot, roomDir = null }) {
+  const canonical = resolve(source);
+  const allowed = [resolve(projectRoot), ...(roomDir ? [resolve(roomDir)] : [])];
+  if (!allowed.some((root) => canonical === root || canonical.startsWith(root + sep))) throw new Error('A module can only be installed from a file inside the project or the room folder.');
+  const text = await readFile(canonical, 'utf8');
+  return installModuleText({ text, name: basename(canonical), scope, stateRoot, projectRoot, source: { kind: 'file', from: canonical } });
+}
+
+// Where a module was installed from, if MADRE was told. This is what "update this module" asks
+// again: the file the author keeps it in, or the address they publish it at.
+export async function moduleOrigin(module) {
+  if (!module?.external || !module.file) return null;
+  const declared = module.updates?.url ? { kind: 'url', from: module.updates.url } : null;
+  const remembered = await readFile(module.file.replace(/\.mjs$/, '.source.json'), 'utf8').then((raw) => JSON.parse(raw)).catch(() => null);
+  return declared ?? (remembered?.from ? { kind: remembered.kind ?? 'file', from: remembered.from, at: remembered.at ?? null } : null);
+}
+
+// Removing is for the human's modules only; MADRE's own stay.
+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(() => {});
+  await loadExternalModules({ stateRoot, projectRoot });
+  return { id, name: module.name, file: module.file };
+}
+
 export const moduleById = (id) => MODULES.find((module) => module.id === id) ?? null;
-export function describeModules(ctx) { return Promise.all(MODULES.map((module) => module.describe(ctx))); }
+// What MODULES shows, with each card's update state attached from the cache when the room offers
+// the service. Never a network read: a screen that waits on a registry is a screen that hangs.
+export async function describeModules(ctx) {
+  const items = await Promise.all(MODULES.map((module) => module.describe(ctx)));
+  const look = ctx.services?.moduleUpdate;
+  // One place, at the boundary: what a module says about itself is written in English inside the
+  // module, and it is the card that speaks the room's language. Nothing in the module files
+  // changes, and neither does what a module hands to an agent.
+  if (!look) return translate(items);
+  return translate(await Promise.all(items.map(async (item) => ({ ...item, update: await look(item).catch(() => null) }))));
+}
 // One flat list of every route a module serves, with the module attached.
 export function findModuleRoute(method, pathname) {
   for (const module of MODULES) {
@@ -24,4 +147,13 @@ export function findModuleRoute(method, pathname) {
   }
   return null;
 }
+// Every slash command the modules declare, with its module attached.
+export function moduleCommands() {
+  return MODULES.flatMap((module) => (module.slash ?? []).map((command) => ({ ...command, module })));
+}
+// Every tool server the modules hand to one turn, flattened; a module that fails hands nothing.
+export async function toolsForTurn(ctx, turn) {
+  const lists = await Promise.all(MODULES.filter((module) => module.toolsForTurn).map((module) => module.toolsForTurn(ctx, turn)));
+  return lists.flat().filter((server) => server && server.name && server.command);
+}
 export { defineModule } from './sdk.mjs';

package/src/modules/ollama.mjs

@@ -2,33 +2,81 @@
 // Ollama runs. The server offers the wiring through ctx.services.ollama.
 
 import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.mjs';
+import { findOnPath } from './helpers.mjs';
 import { RECOMMENDED } from '../ollama.mjs';
 
+// Ollama is not an npm package, so each system has its own way in. Where MADRE can run it, the
+// command is shown on the button before it runs; where it cannot, it hands over the download.
+export function ollamaInstallPlan({ platform = process.platform, brew = null } = {}) {
+  if (platform === 'darwin') {
+    return brew
+      ? { command: brew, args: ['install', 'ollama'], display: 'brew install ollama', note: 'Installs Ollama with Homebrew, the package manager already on this computer.' }
+      : { command: null, download: 'https://ollama.com/download', display: null, note: 'Homebrew is not on this computer. Download Ollama from ollama.com, open it once, and press RECHECK.' };
+  }
+  if (platform === 'linux') {
+    return { command: 'sh', args: ['-c', 'curl -fsSL https://ollama.com/install.sh | sh'], display: 'curl -fsSL https://ollama.com/install.sh | sh', note: "Ollama's own install script, downloaded from ollama.com and run on this computer." };
+  }
+  return { command: null, download: 'https://ollama.com/download', display: null, note: 'Download the Ollama installer from ollama.com, run it, and press RECHECK.' };
+}
+
+// A newer Ollama. Where MADRE can do it, the command is shown before it runs; where it cannot,
+// it hands over the download rather than pretending.
+export function ollamaUpdatePlan({ platform = process.platform, brew = null } = {}) {
+  if (platform === 'darwin') {
+    return brew
+      ? { command: brew, args: ['upgrade', 'ollama'], display: 'brew upgrade ollama', note: 'Upgrades Ollama with Homebrew. Your models stay where they are.' }
+      : { command: null, download: 'https://ollama.com/download', display: null, note: 'Ollama was not installed with Homebrew. Download the newer one from ollama.com, open it once, and press RECHECK. Your models stay where they are.' };
+  }
+  if (platform === 'linux') {
+    return { command: 'sh', args: ['-c', 'curl -fsSL https://ollama.com/install.sh | sh'], display: 'curl -fsSL https://ollama.com/install.sh | sh', note: "Ollama's own install script upgrades in place. Your models stay where they are." };
+  }
+  return { command: null, download: 'https://ollama.com/download', display: null, note: 'Download the newer Ollama from ollama.com and run it. Your models stay where they are.' };
+}
+
+// Waking it: the same command on every system, and the app on macOS does it too.
+export const ollamaStartPlan = () => ({ command: 'ollama', args: ['serve'], display: 'ollama serve' });
+
+// What the room needs to know about the local brain: its own state, whether it is even on this
+// computer, and the one step that moves it forward. The card and the routes share this.
+export async function ollamaView(probe, settings) {
+  const binary = await findOnPath('ollama');
+  return { ...probe, settings, binary, install: ollamaInstallPlan({ brew: await findOnPath('brew') }), start: ollamaStartPlan() };
+}
+
 export default defineModule({
   id: 'ollama',
   name: 'OLLAMA',
   vendor: 'MADRE · LOCAL INTELLIGENCE',
-  summary: 'Recall by meaning and memory distillation on this machine through Ollama: no provider tokens, nothing leaves. Needs Ollama running with an embedding model and a chat model; MADRE can pull the recommended ones.',
-  creates: ['nothing in the project', 'an ollama block in ~/.pulse/config.json', 'models in Ollama\'s own store when you press PULL'],
-  requires: ['Ollama installed and running (ollama serve, or the Ollama app)'],
+  tracks: { name: 'ollama', github: 'ollama/ollama' },
+  summary: 'Recall by meaning and memory distillation on this machine, through Ollama: no provider tokens, nothing leaves.',
+  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 },
   card: 'ollama',
   async status(ctx) {
     const probe = ctx.services.ollama?.state() ?? { running: false, models: [], embedModel: null, chatModel: null };
+    const view = await ollamaView(probe, ctx.settings);
+    const binary = view.binary;
     const settings = ctx.settings;
-    const roles = [settings.embeddings && probe.embedModel ? `embeddings · ${probe.embedModel}` : null, settings.archivist && probe.chatModel ? `archivist · ${probe.chatModel}` : null, settings.agent !== false && probe.chatModel ? '@madre in the room' : null].filter(Boolean);
-    const detail = !probe.running ? 'not running · start Ollama and RECHECK'
-      : !settings.enabled ? `off · ${probe.models.length} model${probe.models.length === 1 ? '' : 's'} available`
-        : roles.length ? `on · ${roles.join(' · ')}` : 'on · no usable model yet · PULL one';
+    const roles = [settings.embeddings && probe.embedModel ? `${t('embeddings')} · ${probe.embedModel}` : null, settings.archivist && probe.chatModel ? `${t('archivist')} · ${probe.chatModel}` : null, settings.agent !== false && probe.chatModel ? t('@madre in the room') : null].filter(Boolean);
+    const detail = !probe.running ? (binary ? t('installed, not running · START it here') : t('not installed · INSTALL it here'))
+      : !settings.enabled ? t('off · {n} models available', { n: probe.models.length })
+        : roles.length ? `${t('on')} · ${roles.join(' · ')}` : t('on · no usable model yet · PULL one');
     return {
+      runs: [{ name: 'ollama', version: probe.version ?? null }],
       models: probe.models.map((model) => model.name),
       status: { installed: settings.enabled && probe.running && roles.length > 0, detail },
-      ollama: { ...probe, settings },
+      ollama: view,
       recommended: RECOMMENDED,
       preflight: probe.running ? { ok: true, problems: [] } : { ok: false, problems: ['Ollama is not running: open the Ollama app or run `ollama serve`, then RECHECK.'] },
       install: { display: settings.enabled ? 'disable Ollama' : 'enable Ollama (config.json)', platforms: [] },
     };
   },
+  async updatePlan(ctx) {
+    const { findOnPath } = await import('./helpers.mjs');
+    return ollamaUpdatePlan({ brew: await findOnPath('brew') });
+  },
   async toggle(ctx) {
     const enabled = !(ctx.settings.enabled ?? true);
     await ctx.updateConfig({ modules: { ...(ctx.config.modules ?? {}), ollama: { ...(ctx.config.modules?.ollama ?? {}), enabled } } });
@@ -37,14 +85,22 @@ export default defineModule({
     return { status: 200, body: { enabled, ollama: status } };
   },
   routes: [
-    { method: 'GET', path: '/api/ollama', handler: async (ctx) => ({ status: 200, body: { ollama: await ctx.services.ollama.wire({ probe: false }), recommended: RECOMMENDED } }) },
-    { method: 'POST', path: '/api/ollama/probe', handler: async (ctx) => ({ status: 200, body: { ollama: await ctx.services.ollama.wire(), recommended: RECOMMENDED } }) },
+    { method: 'GET', path: '/api/ollama', handler: async (ctx) => ({ status: 200, body: { ollama: await ollamaView(await ctx.services.ollama.wire({ probe: false }), ctx.settings), recommended: RECOMMENDED } }) },
+    { method: 'POST', path: '/api/ollama/probe', handler: async (ctx) => ({ status: 200, body: { ollama: await ollamaView(await ctx.services.ollama.wire(), ctx.settings), recommended: RECOMMENDED } }) },
     { method: 'POST', path: '/api/ollama/settings', handler: async (ctx, { payload }) => {
       const next = { ...(ctx.config.modules?.ollama ?? {}) };
       for (const key of ['embeddings', 'archivist', 'agent', 'enabled']) if (typeof payload[key] === 'boolean') next[key] = payload[key];
       await ctx.updateConfig({ modules: { ...(ctx.config.modules ?? {}), ollama: next } });
       return { status: 200, body: { ollama: await ctx.services.ollama.wire({ probe: false }) } };
     } },
+    { method: 'POST', path: '/api/ollama/install', handler: async (ctx) => {
+      const started = await ctx.services.ollama.install();
+      return started.ok ? { status: 202, body: { installing: true, command: started.command } } : { status: started.download ? 412 : 409, body: { error: started.error, download: started.download ?? null } };
+    } },
+    { method: 'POST', path: '/api/ollama/start', handler: async (ctx) => {
+      const started = await ctx.services.ollama.start();
+      return started.ok ? { status: 200, body: { ollama: ctx.services.ollama.state() } } : { status: 412, body: { error: started.error } };
+    } },
     { method: 'POST', path: '/api/ollama/pull', handler: async (ctx, { payload }) => {
       const model = String(payload.model ?? '').trim();
       if (!/^[a-z0-9][a-z0-9._:/-]{1,80}$/i.test(model)) return { status: 400, body: { error: 'Give a model name like nomic-embed-text or qwen2.5:3b.' } };

package/src/modules/playwright.mjs

@@ -3,25 +3,24 @@
 // scratch folder. Runs @playwright/mcp per turn, isolated, with allowed origins limited to the
 // room's own address: nothing else on the network is reachable through it.
 
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
 import { join } from 'node:path';
+import { t } from '../i18n.mjs';
 import { defineModule } from './sdk.mjs';
+import { packageVersion } from './helpers.mjs';
 
-const execFileAsync = promisify(execFile);
+export const PLAYWRIGHT_PACKAGE = '@playwright/mcp';
+export const PLAYWRIGHT_BROWSERS = ['chromium', 'firefox', 'webkit'];
 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'];
 
 let probe = { at: 0, version: null };
-// Is @playwright/mcp installed where npx can find it without downloading? Cached a minute.
-export async function playwrightVersion({ env = process.env, now = Date.now() } = {}) {
-  if (now - probe.at < 60000) return probe.version;
-  let version = null;
-  try {
-    const { stdout } = await execFileAsync('npx', ['--no', '@playwright/mcp', '--version'], { env, timeout: 15000 });
-    version = stdout.trim().split('\n').pop().trim() || 'installed';
-  } catch { version = null; }
+// Is @playwright/mcp installed where npx can find it without downloading? Read from the package
+// itself, never asked of it: `npx --no <package> --version` answers with npm's own version and
+// exits cleanly when the package is not there, so it said 11.16.0 for a server never installed.
+export async function playwrightVersion({ env = process.env, projectRoot = process.cwd(), now = Date.now(), fresh = false } = {}) {
+  if (!fresh && now - probe.at < 60000) return probe.version;
+  const version = await packageVersion(PLAYWRIGHT_PACKAGE, { env, projectRoot });
   probe = { at: now, version };
   return version;
 }
@@ -30,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.`,
@@ -41,33 +43,52 @@ export default defineModule({
   id: 'playwright',
   name: 'PLAYWRIGHT',
   vendor: 'MADRE · Playwright MCP',
-  summary: 'Hands every agent a headless browser that reaches only this MADRE: open the RIPLEY preview of a page, click through it, read the console, take screenshots into the turn\'s scratch folder. Runs @playwright/mcp isolated per turn; no other origin is reachable.',
-  creates: ['nothing in the project: screenshots land in .pulse/out/<turn>/', 'a playwright switch in ~/.pulse/config.json', 'a browser process per turn, started and stopped by the CLI'],
-  requires: ['@playwright/mcp installed (npm install -g @playwright/mcp) and a browser (npx playwright install chromium)', 'RIPLEY on, to have pages to open'],
+  tracks: { name: PLAYWRIGHT_PACKAGE, npm: PLAYWRIGHT_PACKAGE },
+  summary: 'Hands every agent a headless browser that reaches only this room: it opens the RIPLEY preview of a page, clicks through it, reads the console and takes 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 room is reachable through it'],
+  requires: ['@playwright/mcp and a chromium browser on this machine', 'RIPLEY on, to have pages to open'],
   settings: { enabled: false, browser: 'chromium', headless: true },
   card: 'switch',
+  controls: [
+    { key: 'browser', label: 'BROWSER', type: 'select', options: PLAYWRIGHT_BROWSERS, note: 'Which browser engine the agents drive.' },
+    { key: 'headless', label: 'SHOW THE WINDOW', type: 'switch', invert: true, note: 'Off, the browser runs headless. On, it opens on this screen so you can watch.' },
+  ],
   async status(ctx) {
-    const version = await playwrightVersion({ env: ctx.env });
+    const version = await playwrightVersion({ env: ctx.env, projectRoot: ctx.projectRoot });
     return {
-      version: version ?? null,
-      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? (version ? `on · @playwright/mcp ${version} · ${ctx.settings.browser}` : 'on · @playwright/mcp not found') : version ? `off · @playwright/mcp ${version} found` : 'off · @playwright/mcp not installed' },
-      preflight: version ? { ok: true, problems: [] } : { ok: false, problems: ['Install the browser server first: npm install -g @playwright/mcp && npx playwright install chromium'] },
+      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, 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'] },
     };
   },
+  // Getting the browser server onto this computer, or a newer one. Installed globally, which is
+  // where `npx --no` looks for it at turn time without downloading anything.
+  async updatePlan(ctx, { latest = null } = {}) {
+    const target = latest ? `${PLAYWRIGHT_PACKAGE}@${latest}` : PLAYWRIGHT_PACKAGE;
+    return {
+      command: 'npm',
+      args: ['install', '-g', target],
+      display: `npm install -g ${target}`,
+      note: 'Installs the browser server for every project on this computer. A browser itself may still be missing; the card says so if it is.',
+      after: async () => { await playwrightVersion({ env: ctx.env, projectRoot: ctx.projectRoot, fresh: true }); },
+    };
+  },
   async toolsForTurn(ctx, turn) {
-    if (!(await playwrightVersion({ env: ctx.env }))) return [];
+    if (!(await playwrightVersion({ env: ctx.env, projectRoot: ctx.projectRoot }))) return [];
     if (turn.mode === 0) return [];   // a ghost turn leaves no screenshots and opens no browser
     const outputDir = turn.scratchDir ?? join(turn.roomDir ?? ctx.stateRoot, 'playwright');
     return [playwrightServerFor({ port: turn.port, outputDir, browser: ctx.settings.browser ?? 'chromium', headless: ctx.settings.headless !== false })];
   },
   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'], win32: ['npm install -g @playwright/mcp', 'npx playwright install 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'] },
   }],
 });