@jossuealcala/madre 0.6.0 → 0.7.0

package/src/modules/sdk.mjs

@@ -4,7 +4,8 @@
 // context (ctx) per call and hands it in; the module never reaches for globals.
 //
 //   ctx = { projectRoot, stateRoot, config, settings, env, agents, room, readConfig(), updateConfig(patch),
-//           record(type, payload), services: { ... what the server offers } }
+//           record(type, payload), services: { ... what the server offers },
+//           vault: { get, held, keep, forget } — this module's own secrets, and only its own }
 //
 // A module may also hand tools to every turn: `toolsForTurn(ctx, turn)` returns MCP server
 // specs `{ name, command, args, env, tools: [names], brief }` that MADRE attaches to the CLI for
@@ -15,9 +16,22 @@
 // 'installer' writes into the project through a confirmed command.
 
 import { readFile, stat } from 'node:fs/promises';
+import { forgetSecret, readSecret, summary as vaultSummary, writeSecret } from '../vault.mjs';
 
 const camel = (id) => id.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 
+// The vault, narrowed to one module. A connector has no CLI to hand its secret to, so MADRE
+// holds it — and a module must not be able to read somebody else's. It never passes its own id:
+// the id is closed over here, so asking for another module's secret is not a thing a module can
+// express. `held()` is names and lengths; `get()` is the only door to a value, and what comes
+// back belongs in the environment of a process the module spawns, never in a prompt or a reply.
+const vaultFor = (id, stateRoot) => ({
+  get: (name) => readSecret(stateRoot, id, name),
+  held: () => vaultSummary(stateRoot, id),
+  keep: (name, value) => writeSecret(stateRoot, id, name, value),
+  forget: (name = null) => forgetSecret(stateRoot, id, name),
+});
+
 let release = null;
 // MADRE's own release, read once from the package that is running.
 export async function madreRelease() {
@@ -57,8 +71,8 @@ export function dependencies(runs) {
 // 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',
+  'requires', 'models', 'commands', 'card', 'configKey', 'settings', 'controls', 'routes', 'reaches',
+  'conditions', 'slash', 'status', 'preflight', 'detect', 'confirm', 'installCommand', 'secrets',
   'updatePlan', 'toolsForTurn', 'toggle', 'onToggle', 'onSettings', 'onEvent', 'toggledEvent',
   'toggledBody', 'describe',
 ]);
@@ -92,8 +106,27 @@ export function defineModule(spec) {
       if (type === 'select' && !control.options?.length) throw new Error(`Module ${spec.id}: control ${control.key} is a select with no options.`);
       return { key: control.key, label: control.label ?? control.key.toUpperCase(), type, options: control.options ?? [], note: control.note ?? '', invert: Boolean(control.invert) };
     }),
+    // Where this module's traffic goes, in the same four answers `src/outbound.mjs` demands of
+    // MADRE's own destinations. Without it a connector's traffic reads in the log as «an address
+    // nothing here declares», which is true and useless: the human cannot tell a connector they
+    // installed from something going wrong.
+    reaches: (spec.reaches ?? []).map((reach) => {
+      if (!reach?.host || typeof reach.host !== 'string') throw new Error(`Module ${spec.id}: a declared destination needs a host.`);
+      for (const answer of ['to', 'what', 'when']) {
+        if (!reach[answer]) throw new Error(`Module ${spec.id}: destination ${reach.host} does not say ${answer}.`);
+      }
+      return { id: reach.id ?? reach.host, host: reach.host, to: reach.to, what: reach.what, when: reach.when, where: reach.where ?? `MODULES → ${spec.name}`, ...(typeof reach.match === 'function' ? { match: reach.match } : {}) };
+    }),
+    // Secrets this module needs to do its job: declared, not drawn. MADRE renders a paste field
+    // per entry and keeps the value in its vault under this module's name. The card only ever
+    // shows that one is held and how long it is — the value goes nowhere but the module.
+    secrets: (spec.secrets ?? []).map((secret) => {
+      if (!secret?.name || !/^[a-z0-9][a-z0-9_-]*$/i.test(secret.name)) throw new Error(`Module ${spec.id}: a secret needs a plain name.`);
+      return { name: secret.name, label: secret.label ?? secret.name.toUpperCase(), note: secret.note ?? '', where: secret.where ?? '' };
+    }),
   };
   const settingsFrom = (config) => ({ ...defaults, ...(config?.modules?.[configKey] ?? {}) });
+  const mine = (ctx, settings) => ({ ...ctx, settings, vault: vaultFor(spec.id, ctx.stateRoot) });
   const module = {
     ...base,
     configKey,
@@ -113,12 +146,12 @@ export function defineModule(spec) {
     toolsForTurn: spec.toolsForTurn ? async (ctx, turn) => {
       const settings = settingsFrom(ctx.config);
       if (kind === 'builtin' && !settings.enabled) return [];
-      try { return (await spec.toolsForTurn({ ...ctx, settings }, turn)) ?? []; } catch (error) { console.error(`MADRE module ${spec.id}: toolsForTurn failed: ${error.message}`); return []; }
+      try { return (await spec.toolsForTurn(mine(ctx, settings), turn)) ?? []; } catch (error) { console.error(`MADRE module ${spec.id}: toolsForTurn failed: ${error.message}`); return []; }
     } : null,
     // How the outside thing this module drives gets a newer version onto this computer. MADRE
     // shows the command before it runs and never runs one the human has not read. A module that
     // cannot update what it drives returns the note that says where to get it instead.
-    updatePlan: spec.updatePlan ? async (ctx, what) => spec.updatePlan({ ...ctx, settings: settingsFrom(ctx.config) }, what) : null,
+    updatePlan: spec.updatePlan ? async (ctx, what) => spec.updatePlan(mine(ctx, settingsFrom(ctx.config)), what) : null,
     // Legacy installer hooks, kept on the object so the confirm-and-run path can use them.
     detect: spec.detect ?? null,
     preflight: spec.preflight ?? null,
@@ -127,7 +160,7 @@ export function defineModule(spec) {
     // What MODULES shows: base fields plus status, preflight, install line and whatever the module adds.
     async describe(ctx) {
       const settings = settingsFrom(ctx.config);
-      const own = spec.status ? await spec.status({ ...ctx, settings }) : {};
+      const own = spec.status ? await spec.status(mine(ctx, settings)) : {};
       const installed = own.installed ?? (kind === 'builtin' ? Boolean(settings.enabled) : false);
       const runs = dependencies(own.runs);
       const tracked = base.tracks ? (runs.find((dep) => dep.name === base.tracks.name)?.version ?? null) : undefined;
@@ -140,6 +173,8 @@ export function defineModule(spec) {
         versionSource: stamp.source,
         canUpdate: Boolean(spec.updatePlan),
         controls: base.controls.map((control) => ({ ...control, value: settings[control.key] ?? null })),
+        // What is in the vault for this module: names and lengths, never values.
+        ...(base.secrets.length ? { held: await vaultSummary(ctx.stateRoot, spec.id).catch(() => []) } : {}),
         ships: this.external ? null : await madreRelease(),
         runs,
         status: own.status ?? { installed, detail: own.detail ?? (installed ? 'on' : 'off') },
@@ -163,7 +198,7 @@ export function defineModule(spec) {
       }
       const settings = { ...settingsFrom(ctx.config), [key]: next };
       await ctx.updateConfig({ modules: { ...(ctx.config.modules ?? {}), [configKey]: { ...(ctx.config.modules?.[configKey] ?? {}), [key]: next } } });
-      if (spec.onSettings) await spec.onSettings({ ...ctx, settings }, settings);
+      if (spec.onSettings) await spec.onSettings(mine(ctx, settings), settings);
       return { status: 200, body: { settings: Object.fromEntries(base.controls.map((known) => [known.key, settings[known.key] ?? null])) } };
     } : null,
 
@@ -171,11 +206,11 @@ export function defineModule(spec) {
     // A module may guard it (`confirm`) or replace it (`toggle`).
     toggle: kind === 'builtin' || spec.toggle ? async (ctx, payload = {}) => {
       const settings = settingsFrom(ctx.config);
-      if (spec.toggle) return spec.toggle({ ...ctx, settings }, payload);
+      if (spec.toggle) return spec.toggle(mine(ctx, settings), payload);
       const enabled = !settings.enabled;
       if (enabled && spec.confirm && payload.confirm !== true) return { status: 400, body: { error: spec.confirm } };
       await ctx.updateConfig({ modules: { ...(ctx.config.modules ?? {}), [configKey]: { ...(ctx.config.modules?.[configKey] ?? {}), enabled } } });
-      const after = spec.onToggle ? await spec.onToggle({ ...ctx, settings: { ...settings, enabled } }, enabled) : null;
+      const after = spec.onToggle ? await spec.onToggle(mine(ctx, { ...settings, enabled }), enabled) : null;
       await ctx.record('extension.toggled', { id: spec.id, name: base.name, enabled, ...(spec.toggledEvent ?? {}) });
       return { status: 200, body: { enabled, ...(after ?? {}), ...(spec.toggledBody?.(enabled) ?? {}) } };
     } : null,

package/src/outbound.mjs

@@ -99,7 +99,39 @@ export const DESTINATIONS = [
 ];
 
 const byId = new Map(DESTINATIONS.map((one) => [one.id, one]));
-export const destination = (id) => byId.get(id) ?? null;
+export const destination = (id) => byId.get(id) ?? declaredById.get(id) ?? null;
+
+// What a module declares it reaches.
+//
+// The list above is the core's, written in code and not editable at runtime — that is the whole
+// point of it. A connector, though, is a module, and a module that reaches a service nobody
+// declared shows up in the log as «went to an address nothing here declares», which is true and
+// useless: the human cannot tell a connector they installed from something going wrong.
+//
+// So a module may declare its own, in the same shape and answering the same four questions. It is
+// held apart from the core's and MARKED, because who promised what is part of the promise: MADRE
+// vouches for the list above and only reports the ones below. A declaration is rebuilt from the
+// modules on every load, so uninstalling one takes its destination with it.
+const declaredById = new Map();
+export function declareDestinations(moduleId, reaches = []) {
+  for (const one of Array.isArray(reaches) ? reaches : []) {
+    if (!one?.host || typeof one.host !== 'string') continue;
+    const id = `${moduleId}:${one.id ?? one.host}`;
+    declaredById.set(id, {
+      id,
+      host: one.host.toLowerCase(),
+      match: typeof one.match === 'function' ? one.match : null,
+      to: String(one.to ?? one.host),
+      what: String(one.what ?? ''),
+      when: String(one.when ?? ''),
+      where: String(one.where ?? `MODULES → ${moduleId.toUpperCase()}`),
+      inside: true,
+      module: moduleId,
+    });
+  }
+}
+export function clearDeclaredDestinations() { declaredById.clear(); }
+export const declaredDestinations = () => [...declaredById.values()];
 
 // Which declaration a URL belongs to. An address nobody declared is said to be exactly that.
 export function classify(rawUrl, { reportHost = null } = {}) {
@@ -108,10 +140,12 @@ export function classify(rawUrl, { reportHost = null } = {}) {
   const host = url.hostname.replace(/^\[|\]$/g, '');
   if (LOCAL.has(host)) return { id: url.port === '11434' ? 'ollama' : 'room', to: `${host}:${url.port || '80'}`, local: true };
   if (reportHost && host === reportHost) return { id: 'reports', to: byId.get('reports').to, local: false };
-  for (const one of DESTINATIONS) {
+  for (const one of [...DESTINATIONS, ...declaredById.values()]) {
     if (!one.host || one.host !== host) continue;
     if (one.match && !one.match(url)) continue;
-    return { id: one.id, to: one.to, local: false };
+    // `module` travels so the log can say who vouched for this address. MADRE's own declarations
+    // and a module's are both honest; they are not the same promise.
+    return { id: one.id, to: one.to, local: false, ...(one.module ? { module: one.module } : {}) };
   }
   return { id: 'unknown', to: host, local: false };
 }

package/src/ports.mjs

@@ -18,8 +18,13 @@ const NOISE = /^(rapportd|sharingd|identityservicesd|controlce|remoted|launchd|m
 // One `lsof -nP -iTCP -sTCP:LISTEN` table into the ports a human might want to look at.
 // Loopback only: a line bound to * or 0.0.0.0 is reachable from the network, and this room does
 // not help anyone frame that by accident.
-export function parseListening(output = '', { self = null } = {}) {
+// Everything listening, split by whether RIPLEY may open it. The wider half is NOT a list of
+// things to show as openable — it is the answer to «there is nothing here», which was a lie:
+// `node server.js` and `python -m http.server` bind every interface by default, so the most
+// common case in the world was being discarded in silence and reported as an empty computer.
+export function classifyListening(output = '', { self = null } = {}) {
   const found = new Map();
+  const wider = new Map();
   for (const line of String(output ?? '').split('\n').slice(1)) {
     const match = line.match(/^(\S+)\s+(\d+)\s+\S+\s+\S+\s+(IPv4|IPv6)\s+\S+\s+\S+\s+\S+\s+(\S+)\s+\(LISTEN\)/);
     if (!match) continue;
@@ -29,13 +34,28 @@ export function parseListening(output = '', { self = null } = {}) {
     const host = address.slice(0, address.lastIndexOf(':'));
     const port = Number(address.slice(address.lastIndexOf(':') + 1));
     if (!Number.isInteger(port) || port <= 0 || port > 65535) continue;
-    if (!['127.0.0.1', '[::1]', 'localhost'].includes(host)) continue;
     if (SYSTEM_PORTS.has(port) || NOISE.test(command)) continue;
     if (self && port === Number(self)) continue;
+    if (!['127.0.0.1', '[::1]', 'localhost'].includes(host)) {
+      // Bound to every interface, so reachable from the network. Not offered, but counted: the
+      // human deserves to know their server is there and why it is not on the list.
+      if (['*', '0.0.0.0', '[::]'].includes(host) && !wider.has(port)) wider.set(port, { port, pid: Number(pid), command, host });
+      continue;
+    }
     const seen = found.get(port);
     if (!seen) found.set(port, { port, pid: Number(pid), command });
   }
-  return [...found.values()].sort((a, b) => a.port - b.port);
+  const byPort = (a, b) => a.port - b.port;
+  return {
+    ports: [...found.values()].sort(byPort),
+    // A port answering on both loopback and every interface is already openable; it is not news.
+    wider: [...wider.values()].filter((one) => !found.has(one.port)).sort(byPort),
+  };
+}
+
+// What RIPLEY may open, which is what nearly every caller wants.
+export function parseListening(output = '', options = {}) {
+  return classifyListening(output, options).ports;
 }
 
 // Whether a server agrees to be put behind glass. A page can refuse, and refusing is the correct

package/src/request-guard.mjs

@@ -0,0 +1,26 @@
+// 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.
+//
+//  · Host has to name this computer. A page that points its own domain at 127.0.0.1 (DNS
+//    rebinding) still sends its domain as Host, so it never reaches a route — reads included.
+//  · A browser says who is asking in Origin. Anything that changes state has to come from the
+//    room's own page. A terminal, an agent's curl or MADRE's own CLI send no Origin and pass.
+
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]']);
+const SAFE = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+export function hostIsLocal(host) {
+  if (typeof host !== 'string' || !host) return false;
+  const name = host.startsWith('[') ? host.slice(0, host.indexOf(']') + 1) : host.split(':')[0];
+  return LOOPBACK.has(name.toLowerCase());
+}
+
+// null when the request may go on, otherwise the reason it may not.
+export function refuseForeign({ method = 'GET', headers = {} } = {}) {
+  if (!hostIsLocal(headers.host)) return 'MADRE answers only when it is called by this computer\'s name (127.0.0.1 or localhost).';
+  const origin = headers.origin;
+  if (SAFE.has(method) || origin === undefined) return null;
+  if (origin === `http://${headers.host}` || origin === `https://${headers.host}`) return null;
+  return 'A page from somewhere else cannot act in this room.';
+}

package/src/room/archivist.mjs

@@ -95,7 +95,8 @@ export class Archivist {
       const started = Date.now();
       try {
         const local = agent.adapter === 'ollama';
-        const prompt = distillPrompt({ entries: batch.entries, projectName: this.#deps.projectName(), existing: this.#memory.memories({ limit: 12 }), json: local });
+        const brief = this.#memory.briefing();
+        const prompt = distillPrompt({ entries: batch.entries, projectName: this.#deps.projectName(), existing: brief.standing, discarded: brief.discarded, json: local });
         const result = await invokers[agent.adapter]({ executable: agent.path, projectRoot: this.#deps.projectRoot(), prompt, timeoutMs: local ? this.#deps.localTimeoutMs() : this.#deps.timeoutFor(agent.id), model: local ? null : this.#settings.model, json: local, attachments: [], lease: null, scopes: { web: false, imageGen: false }, imageStudio: null });
         const memories = parseDistillation(result?.text, { fromSequence: batch.fromSequence, throughSequence: batch.throughSequence });
         const added = this.#memory.addMemories(memories, { agent: agent.id, fromSequence: batch.fromSequence, throughSequence: batch.throughSequence });

package/src/room/prompt.mjs

@@ -104,7 +104,7 @@ export function promptParts({
       mcpServers.length
         ? `Tools from MADRE's modules, attached to this turn as MCP servers:\n${mcpServers.map((server) => `- ${server.name}: ${server.brief ?? (server.tools?.length ? server.tools.join(', ') : 'see its tool list')}`).join('\n')}`
         : null },
-    { id: 'sdk', text: lease && sdk && wantsModule(text) ? `Building a MADRE module: MADRE is modular and the human may ask you for a module (a slash command, a tool for the agents, an integration). Read the SDK guide at ${sdk.guide} and the complete example at ${sdk.example}, then write ONE file named <id>.module.mjs (default export a plain spec object) ${lease.scratchDir ? `in ${lease.outDir}/${lease.scratchDir}` : 'in the lease'}. Do not touch ~/.pulse/modules or .madre/modules: MADRE shows the human an INSTALL card and they decide. A module runs inside MADRE with the human's permissions, so keep it small, honest about what it reaches, and never store credentials.` : null },
+    { id: 'sdk', text: lease && sdk && wantsModule(text) ? `Building a MADRE module: MADRE is modular and the human may ask you for a module (a slash command, a tool for the agents, an integration). Read the SDK guide at ${sdk.guide} and the complete example at ${sdk.example}. If it talks to a service outside this machine, read ${sdk.connector} too: a connector is ONE file that is both the module and the MCP server it spawns, and that shape is not guessable. Then write ONE file named <id>.module.mjs (default export a plain spec object) ${lease.scratchDir ? `in ${lease.outDir}/${lease.scratchDir}` : 'in the lease'}. Do not touch ~/.pulse/modules or .madre/modules: MADRE shows the human an INSTALL card and they decide. A module runs inside MADRE with the human's permissions, so keep it small and honest about what it reaches. Never hardcode a credential or invent somewhere to keep one: declare 'secrets' and read them back with ctx.vault, which is where MADRE keeps them and the only place that is safe.` : null },
     { id: 'lease', text: lease ? leaseInstructions({ outDir: lease.outDir, agentId: agent.id, scopes: lease.scopes, capable: scopesFor(agent.id), imageStudio, control: Boolean(lease.control), create: Boolean(lease.create), airlock: Boolean(lease.airlock), scratchDir: lease.scratchDir ?? null }) : null },
     { id: 'control-held', text: !lease?.control && controlHolder && controlHolder !== agent.id ? `Heads-up: @${controlHolder} currently holds CONTROL and may be changing project files while you work; cite the state you actually read.` : null },
     { id: 'escalation', text: escalation ? `The human was asked to allow file creation for this step and ${escalation === 'timeout' ? 'did not answer in time' : escalation === 'stopped' ? 'stopped the plan' : 'declined'}. Answer read-only: say plainly what you would have created and what it would contain, without creating it.` : null },

package/src/room.mjs

@@ -10,6 +10,7 @@ import { UsageSentinel } from './usage-sentinel.mjs';
 import { BLOCK_SOURCES, buildPrompt, promptParts, sparedChars } from './room/prompt.mjs';
 import { turnCost, observedRate } from './room/economy.mjs';
 import { contextFor } from './room/context.mjs';
+import { VERDICTS } from './memory.mjs';
 import { coldNotes, coldReading } from './cold.mjs';
 import { questionsFor } from './asking.mjs';
 import { coverageExam, consistencyExam, matchExam, exchanges, MATCH_SAMPLE, saysFor } from './exam.mjs';
@@ -28,7 +29,7 @@ import { CODE000_STRIKES } from './mother.mjs';
 import { parseDirectives } from './directives.mjs';
 import { isValidModelName } from './models.mjs';
 import { MODES, SCOPES, SCOPE_LABELS, capabilitySummary, normalizeMode, resolveScopes } from './capabilities.mjs';
-import { createLease, diffSnapshots, snapshot } from './lease.mjs';
+import { createLease, diffSnapshots, namedPaths, snapshot } from './lease.mjs';
 import { stat as statFile } from 'node:fs/promises';
 import { basename as baseName, join as joinPath } from 'node:path';
 import { contentTypeFor } from './files.mjs';
@@ -257,7 +258,7 @@ export class Room {
       outDir: lease.relativeDir,
       scratchDir: lease.scratchDir,
       scopes: SCOPES.filter((scope) => enabled[scope]),
-      unavailable: SCOPES.filter((scope) => !scopes[scope].capable).map((scope) => SCOPE_LABELS[scope]),
+      unavailable: SCOPES.filter((scope) => !scopes[scope].capable),
       planId,
     });
     await this.#emit('mode.granted', { requestId, planId, agent: step.agent, mode, step: index + 1, scope: decision.decision, leaseId: lease.leaseId, message: decision.decision === 'plan' ? `#${mode} granted for the rest of the plan; every writable agent creates inside one lease.` : `#${mode} granted to @${step.agent} for step ${index + 1} only.` });
@@ -345,6 +346,12 @@ export class Room {
     } catch { return null; }
   }
 
+  // Counts only, for the MEMORY dashboard. See RoomMemory#activity.
+  memoryActivity({ days = 30 } = {}) {
+    if (!this.#memory) return null;
+    try { return this.#memory.activity({ days }); } catch { return null; }
+  }
+
   /* ---------- MU/TH/UR's channel ---------- */
 
   motherStatus() { return this.#mother ? this.#mother.status() : null; }
@@ -616,11 +623,15 @@ export class Room {
     return result;
   }
 
-  // The human's verdict on a reply: good, bad, or cleared. The dataset listens.
+  // The human's verdict on a reply: good, bad, or cleared. The dataset listens, and so does the
+  // archive: what the room distilled from that reply changes standing, without a word of it being
+  // rewritten. The text of a note is what the archivist heard; where it stands is what you said.
   async rateMessage(messageId, rating) {
     if (typeof messageId !== 'string' || !messageId.trim()) throw new Error('Which reply? Give its messageId.');
-    if (!['good', 'bad', 'none'].includes(rating)) throw new Error('A rating is good, bad or none.');
-    return this.#emit('message.rated', { messageId, rating, by: 'you' });
+    if (!VERDICTS.includes(rating)) throw new Error(`A verdict is one of ${VERDICTS.join(', ')}.`);
+    const event = await this.#emit('message.rated', { messageId, rating, by: 'you' });
+    this.#memory?.judge(messageId, rating);
+    return event;
   }
 
   // Forgetting is recorded in the ledger like anything else the human does to the room.
@@ -881,7 +892,10 @@ export class Room {
     if (create === true || standing) {
       const scopes = this.scopesFor(parsed.target);
       const enabled = SCOPES.filter((scope) => scopes[scope].enabled && scopes[scope].wired);
-      const unavailable = SCOPES.filter((scope) => !scopes[scope].capable).map((scope) => SCOPE_LABELS[scope]);
+      // The ids travel; the labels only build the English sentence below. A label is already a
+      // word, so the client's translator had nothing to look up and left it as it found it.
+      const unavailable = SCOPES.filter((scope) => !scopes[scope].capable);
+      const unavailableSaid = unavailable.map((scope) => SCOPE_LABELS[scope]);
       const disabled = SCOPES.filter((scope) => scopes[scope].capable && !scopes[scope].enabled && scopes[scope].wired).map((scope) => SCOPE_LABELS[scope]);
       if (!enabled.includes('write') || scopes.maxMode < 2) {
         const alternatives = this.#agents.filter((agent) => agent.ready && agent.id !== parsed.target && this.scopesFor(agent.id).maxMode >= 2).map((agent) => `@${agent.id}`);
@@ -892,7 +906,7 @@ export class Room {
           unavailable,
           disabled,
           alternatives,
-          message: `@${parsed.target} will answer read-only: ${scopes.write.capable ? 'file creation is switched off for it (enable it in CONNECTIONS)' : 'its CLI cannot create files'}${unavailable.length ? `; it cannot ${unavailable.join(' or ')}` : ''}.${alternatives.length ? ` For creation ask ${alternatives.join(' or ')}.` : ''}`,
+          message: `@${parsed.target} will answer read-only: ${scopes.write.capable ? 'file creation is switched off for it (enable it in CONNECTIONS)' : 'its CLI cannot create files'}${unavailableSaid.length ? `; it cannot ${unavailableSaid.join(' or ')}` : ''}.${alternatives.length ? ` For creation ask ${alternatives.join(' or ')}.` : ''}`,
         });
       } else {
         lease = await this.#projectLease({ leaseId: randomUUID(), messageId });
@@ -982,6 +996,27 @@ export class Room {
     await this.#emit('room.alert', { code, message, plans: this.activePlans().length, turns: this.#turns.size });
   }
 
+  // Human brake for ONE answer, which is a different thing from the master brake. STOPALL takes
+  // down every plan and every agent in the room and is meant for when things have run away;
+  // this takes down the one turn you are looking at, because an agent that has hung or started
+  // down the wrong road should not cost the whole room to stop. The agent's process dies with the
+  // abort and the turn records its own failure the way any other failure does.
+  async stopTurn(messageId, reason = t('stopped by the human')) {
+    const turn = this.#turns.get(messageId);
+    if (!turn) return false;
+    // Marked before the abort lands, so the failure it causes carries the mark: the turn ends
+    // like any other failure because the process really was killed, and only this says it was
+    // asked for.
+    turn.stoppedByHuman = true;
+    await this.#emit('turn.stopped', { messageId, agent: turn.agent, planId: turn.planId, reason, by: 'you' });
+    turn.controller.abort(reason);
+    // Waited out, the way the master brake waits: aborting only asks, and the turn still has to
+    // kill its process and record how it ended. Returning before that leaves the caller — and
+    // anything tidying up after it — racing a write that has not happened yet.
+    await turn.promise?.catch(() => {});
+    return true;
+  }
+
   // Human brake: stops the remaining steps of a running plan and interrupts
   // the step in flight. Recorded in the log like everything else.
   async stopPlan(planId, reason = 'stopped by the human') {
@@ -1253,7 +1288,7 @@ export class Room {
         outDir: lease.relativeDir,
         scratchDir: lease.scratchDir,
         scopes: ['write'],
-        unavailable: SCOPES.filter((scope) => !agentScopes[scope].capable).map((scope) => SCOPE_LABELS[scope]),
+        unavailable: SCOPES.filter((scope) => !agentScopes[scope].capable),
         planId,
       });
     }
@@ -1345,6 +1380,21 @@ export class Room {
       // CREATE: what appeared stays and is shown; what existed before is put back and said.
       const createChanges = createRun ? await this.#controlDesk.settle(createRun) : null;
       const artifacts = createChanges ? await this.#artifactsFrom(createChanges.files) : lease && !lease.control ? diffSnapshots(before, await snapshot(lease.outDir), { relativeDir: lease.relativeDir }) : [];
+      // A turn that could write, wrote nothing, and answers naming files. That is the shape of a
+      // write refused without a word — a headless CLI cannot stop to ask, so what the policy does
+      // not allow simply fails and the model reports the file as created. The room does not read
+      // the prose for a claim; it takes the paths the reply names and asks the disk. Only what is
+      // named AND absent is said, so an agent talking about files that exist says nothing here.
+      if (lease && !lease.control && artifacts.length === 0) {
+        const roots = [this.#projectRoot, lease.outDir, lease.realOutDir].filter(Boolean);
+        const named = namedPaths(result.text, { roots });
+        const missing = [];
+        for (const path of named.slice(0, 12)) {
+          const full = path.startsWith('/') ? path : joinPath(this.#projectRoot, path);
+          if (!(await statFile(full).then(() => true, () => false))) missing.push(path);
+        }
+        if (missing.length) await this.#emit('create.missing', { messageId: responseMessageId, agent: agent.id, planId, files: missing });
+      }
       // CONTROL: what really changed in the project, forbidden zones reverted on the spot.
       const controlChanges = controlRun ? await this.#controlDesk.settle(controlRun) : null;
       const directives = mayDelegate
@@ -1421,7 +1471,7 @@ export class Room {
           await this.#emit('turn.cost', { agent: agent.id, mode: turnMode, responseMessageId, ash: Boolean(cost.blocks.ash), failed: true, spared: shape.spared, ...cost });
         }
       }
-      await this.#emit('message.failed', { messageId, target: agent.id, planId, error: this.#privacy ? this.#privacy.redact(failureMessage(error)).text : failureMessage(error) });
+      await this.#emit('message.failed', { messageId, target: agent.id, planId, error: this.#privacy ? this.#privacy.redact(failureMessage(error)).text : failureMessage(error), ...(this.#turns.get(messageId)?.stoppedByHuman ? { stopped: true } : {}) });
       return null;
     } finally {
       // Release CONTROL whichever way the turn ended; the checkpoint stays for UNDO.

package/src/sentinel-errors.mjs

@@ -100,8 +100,12 @@ export class ErrorSentinel {
   // A room event goes by: a failure MU/TH/UR cannot classify is worth a report.
   async observe(event) {
     if (event?.type !== 'message.failed') return null;
-    const { target, error } = event.payload ?? {};
+    const { target, error, stopped } = event.payload ?? {};
     if (typeof error !== 'string' || !error.trim()) return null;
+    // A turn the human stopped is not a condition. It ends exactly like a failure because the
+    // process really was killed, but nothing went wrong and there is nothing for anyone to
+    // diagnose — filing it would be reporting the brake as a fault.
+    if (stopped) return null;
     const known = diagnose(error, target ?? null);
     if (known.length) return null;
     return this.record({ kind: 'unknown', agent: target ?? null, error, at: event.timestamp });

package/src/server.mjs

@@ -2,7 +2,7 @@ import http from 'node:http';
 import { readFile, realpath, writeFile, mkdir, rm, cp, rename, access } from 'node:fs/promises';
 import { rmSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { parseListening, probePort, framable } from './ports.mjs';
+import { classifyListening, probePort, framable } from './ports.mjs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
@@ -48,9 +48,11 @@ import { applyConfigToEnv, loadConfig } from './config.mjs';
 import { extensionById, findOnPath, runInstaller } from './extensions.mjs';
 import { accountNoteFor, installPlanFor, looksLikeAdminProblem, loginPlanFor, probeAgentAuth, probeAll, TAKES_KEY } from './auth-probe.mjs';
 import { applyKey, keyPlanFor } from './credentials.mjs';
+import { forgetSecret, summary as vaultSummary, writeSecret } from './vault.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';
+import { bootWhatsNew, markSeen, notesFor, whatsNew } from './whats-new.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/' };
@@ -67,7 +69,9 @@ import { planFileOp, CREATIONS } from './file-ops.mjs';
 import { Eyecat } from './eyecat-watch.mjs';
 import { economy } from './room/economy.mjs';
 import { maturity } from './maturity.mjs';
+import { memoryDashboard } from './memory-dashboard.mjs';
 import { verdictFor } from './verdict.mjs';
+import { refuseForeign } from './request-guard.mjs';
 
 const sourceDirectory = dirname(fileURLToPath(import.meta.url));
 const publicDirectory = join(sourceDirectory, '..', 'public');
@@ -145,6 +149,9 @@ export async function createPulseServer({
   ollamaProbe = process.env.PULSE_OLLAMA === '0' ? async () => ({ running: false, host: null, models: [], embedModel: null, chatModel: null, disabled: true }) : probeOllama,
 }) {
   const root = stateRoot ?? process.env.PULSE_HOME ?? join(homedir(), '.pulse');
+  // Read before this run creates anything: whether this person used MADRE before decides whether
+  // an update has news to show them, or this is a first install with nothing to catch up on.
+  const novelty = await bootWhatsNew({ root, version: PACKAGE.version }).catch(() => ({ returning: false }));
   // ~/.pulse/config.json fills in whatever the environment did not set.
   applyConfigToEnv(await loadConfig(root));
   // What language the screens speak. The prompt the agents read is not one of them, and the
@@ -201,7 +208,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, roomLanguage()) : null, envWins: process.env.PULSE_UPDATE_CHECK !== undefined };
+    return { project: canonicalProjectRoot, ...check, notes: Boolean(notesFor(PACKAGE.version)), 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,
@@ -847,6 +854,8 @@ export async function createPulseServer({
   }
 
   const server = http.createServer(async (request, response) => {
+    const foreign = refuseForeign(request);
+    if (foreign) return sendJson(response, 403, { error: t(foreign), guarded: true });
     const url = new URL(request.url, 'http://127.0.0.1');
     // The project's own folder name, typed by the human. Declared at the top of the handler and
     // not beside the first route that happened to need it: a const sits in its temporal dead zone
@@ -1116,17 +1125,20 @@ export async function createPulseServer({
       }
       if (request.method === 'GET' && url.pathname === '/api/ports') {
         if (!(await ripleyOn())) return sendJson(response, 412, { error: t('RIPLEY is off. Enable it in MODULES to render files.') });
-        let listening = [];
+        let listening = { ports: [], wider: [] };
         try {
           const { stdout } = await execFileAsync('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN'], { timeout: 4000, maxBuffer: 2 * 1024 * 1024 });
-          listening = parseListening(stdout, { self: request.socket.localPort });
-        } catch { return sendJson(response, 200, { ports: [], probed: false }); }
+          listening = classifyListening(stdout, { self: request.socket.localPort });
+        } catch { return sendJson(response, 200, { ports: [], wider: [], probed: false }); }
         const ports = [];
-        for (const found of listening.slice(0, 24)) {
+        for (const found of listening.ports.slice(0, 24)) {
           const probe = await probePort(found.port, { fetchImpl: reportFetch });
           if (probe.ok) ports.push({ ...found, status: probe.status, html: probe.html, contentType: probe.contentType, framable: probe.framable });
         }
-        return sendJson(response, 200, { ports, probed: true });
+        // What is listening on every interface travels too. It is not offered — this room does not
+        // help anyone frame something reachable from the network — but saying nothing about it is
+        // what made an empty list read as «there is nothing here» when there plainly was.
+        return sendJson(response, 200, { ports, wider: listening.wider.slice(0, 8).map(({ port, command }) => ({ port, command })), probed: true });
       }
       if (request.method === 'GET' && url.pathname === '/api/questions') {
         const limit = Math.min(5, Math.max(1, Number(url.searchParams.get('limit') ?? 3) || 3));
@@ -1261,6 +1273,15 @@ export async function createPulseServer({
         } catch (error) { return sendJson(response, 400, { error: error.message }); }
       }
       // Release channel: current, latest on npm, and the command for how this copy runs.
+      // What this version brings, once, to someone who came from an older one.
+      if (request.method === 'GET' && url.pathname === '/api/whats-new') {
+        const news = await whatsNew({ root, version: PACKAGE.version, returning: novelty.returning, any: url.searchParams.get('any') === '1' });
+        return sendJson(response, 200, { ...news, changes: { es: releaseUrl(PACKAGE.repository, PACKAGE.version, 'es'), en: releaseUrl(PACKAGE.repository, PACKAGE.version, 'en') } });
+      }
+      if (request.method === 'POST' && url.pathname === '/api/whats-new/seen') {
+        await markSeen(root, PACKAGE.version);
+        return sendJson(response, 200, { seen: PACKAGE.version });
+      }
       if (request.method === 'GET' && url.pathname === '/api/version') {
         return sendJson(response, 200, await versionView({ force: url.searchParams.get('force') === '1' }));
       }
@@ -1325,6 +1346,11 @@ export async function createPulseServer({
           verdict: verdictFor({ maturity: grown, exams: exams.last, cold: research?.cold, asks: research?.ask?.length ?? 0 }),
         });
       }
+      // The MEMORY dashboard: what the archive did day by day and what it is made of. Counts
+      // only, no text of any memory, so it is read like /api/maturity, without the designation.
+      if (request.method === 'GET' && url.pathname === '/api/memory/dashboard') {
+        return sendJson(response, 200, { dashboard: memoryDashboard({ activity: room.memoryActivity(), stats: room.memoryStats() }) });
+      }
       // Inside the core: the document MADRE writes in the human's name for the next turn, block
       // by block. Built on demand and stored nowhere; asking costs nothing and sends nothing.
       if (request.method === 'GET' && url.pathname === '/api/briefing') {
@@ -1497,6 +1523,34 @@ export async function createPulseServer({
       }
       // A provider key for a CLI that signs in from its own prompt. Local connections only: a key
       // pasted from another machine would travel the network. It is written where that CLI looks
+      // A connector's secret. Same rule as an agent's key and for the same reason: it is accepted
+      // only from this computer, never over the network. What differs is where it lands — a
+      // connector has no CLI to hand it to, so MADRE holds it, in its own vault, `0600`, and never
+      // in the config, the ledger or a log. The ledger records that one was set and under which
+      // name; the value never leaves src/vault.mjs except to the module that owns it.
+      const vaultMatch = url.pathname.match(/^\/api\/x\/([a-z0-9-]+)\/secret$/);
+      if (vaultMatch && (request.method === 'POST' || request.method === 'DELETE')) {
+        const id = vaultMatch[1];
+        const address = request.socket.remoteAddress ?? '';
+        if (!['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(address)) {
+          return sendJson(response, 403, { error: t('A key is only accepted from this computer, never over the network.') });
+        }
+        const module = moduleById(id);
+        if (!module) return sendJson(response, 404, { error: t('No module by that name is loaded.') });
+        const payload = await body(request).catch(() => ({}));
+        const name = String(payload.name ?? '');
+        if (request.method === 'DELETE') {
+          const gone = await forgetSecret(root, id, payload.name === undefined ? null : name);
+          if (!gone.ok) return sendJson(response, 400, { error: gone.error });
+          await room.record('module.secret.forgotten', { module: id, name: gone.forgot });
+          return sendJson(response, 200, { ok: true, held: await vaultSummary(root, id) });
+        }
+        const kept = await writeSecret(root, id, name, payload.secret);
+        if (!kept.ok) return sendJson(response, 400, { error: kept.error });
+        // The name and the length, never the secret — the same way privacy counts its terms.
+        await room.record('module.secret.kept', { module: id, name: kept.name, bytes: kept.bytes });
+        return sendJson(response, 200, { ok: true, held: await vaultSummary(root, id) });
+      }
       // for it and never reaches MADRE's config, its ledger or its logs.
       const keyMatch = request.method === 'POST' && url.pathname.match(/^\/api\/agents\/([a-z0-9-]+)\/key$/);
       if (keyMatch) {
@@ -1548,6 +1602,12 @@ export async function createPulseServer({
         await runInstaller({ command: opencode.path, args: ['models'], projectRoot: canonicalProjectRoot, timeoutMs: 20000, onLine: (line) => { if (/^[\w.-]+\/[\w.:-]+$/.test(line.trim())) models.push(line.trim()); } });
         return sendJson(response, 200, { models });
       }
+      // One answer, not the room. The master brake lives next door and means something else.
+      if (request.method === 'POST' && url.pathname === '/api/stop-turn') {
+        const payload = await body(request).catch(() => ({}));
+        const stopped = await room.stopTurn(String(payload.messageId ?? ''));
+        return sendJson(response, stopped ? 200 : 404, stopped ? { stopped: true } : { error: t('That turn is not running any more.') });
+      }
       if (request.method === 'POST' && url.pathname === '/api/stop-all') {
         const result = await room.stopAll();
         return sendJson(response, 202, { stopped: true, ...result });