@jossuealcala/madre 1.0.0 → 1.0.2

package/src/choices.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // An agent asking the human to choose.
 //
 // The room already has one fenced channel, ```pulse, and it puts other agents to work. This is

package/src/cli-args.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Tiny argv reader for the MADRE CLI. Accepts `--name value` and
 // `--name=value`, and remembers which options the user set explicitly so the
 // room can choose sensible defaults (like the next free port) only when they

package/src/cold.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Cold zones: the part of the archive nothing has ever reached for.
 //
 // A memory is cold when three things are true at once, and the three together are what make the

package/src/commands.mjs

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

package/src/config.mjs

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

package/src/conversation-context.mjs

@@ -1,3 +1,17 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
+// What a command's output may weigh in the shared window, and which part of it. It used to be the
+// first 6000 characters: five outputs filled the 16 000 of the window, the request that asked for
+// them went out of it, and the agent lost the thread (2026-10-14). Now it is the start and the end
+// — a test run says what it is at the top and how it went at the bottom — and the agent that asked
+// gets the fuller output in a turn of its own (src/room/returns.mjs).
+const COMMAND_HEAD = 300;
+const COMMAND_TAIL = 900;
+function commandEnds(text) {
+  if (text.length <= COMMAND_HEAD + COMMAND_TAIL) return text;
+  return `${text.slice(0, COMMAND_HEAD)}\n… ${text.length - COMMAND_HEAD - COMMAND_TAIL} characters left out …\n${text.slice(-COMMAND_TAIL)}`;
+}
+
 export function messageEntry(event) {
   if (event.type === 'message.failed') {
     // Failures are part of the conversation: an orchestrator closing a plan
@@ -9,7 +23,7 @@ export function messageEntry(event) {
   if (event.type === 'command.output') {
     const { name, title, text } = event.payload;
     if (typeof text !== 'string' || !text.trim()) return null;
-    return { sequence: event.sequence, messageId: `${event.id}:command`, role: 'command', sender: `/${name}`, target: 'room', text: `${title}\n${text.trim()}`.slice(0, 6000) };
+    return { sequence: event.sequence, messageId: `${event.id}:command`, role: 'command', sender: `/${name}`, target: 'room', text: `${title}\n${commandEnds(text.trim())}` };
   }
   if (event.type !== 'message.created') return null;
   const { messageId, role, sender, target, text } = event.payload;

package/src/credentials.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Handing a provider key to a CLI that signs in from its own prompt.
 //
 // MADRE keeps its promise: it never stores a credential of its own. The key the human pastes is
@@ -36,8 +38,46 @@ export const OPENCODE_PROVIDERS = [
   { id: 'google', label: 'Google AI Studio', keyUrl: 'https://aistudio.google.com/app/apikey' },
 ];
 
+// The rest of the providers OpenCode knows (2026-10-14): its own catalogue, models.dev, which it
+// caches itself. Those a single key opens can be wired from MADRE; the ones that need an account
+// id, a region or a second secret stay with `opencode auth login`. Read only, never fetched.
+export const OPENCODE_FEATURED = ['anthropic', 'openai', 'google', 'openrouter', 'groq', 'deepseek', 'mistral', 'xai', 'togetherai', 'fireworks-ai', 'cerebras', 'perplexity', 'huggingface', 'deepinfra', 'moonshotai', 'zai', 'cohere', 'vercel'];
+export async function readOpenCodeCatalog({ home = homedir(), env = process.env } = {}) {
+  const raw = await readIfThere(join(env.XDG_CACHE_HOME || join(home, '.cache'), 'opencode', 'models.json'));
+  let data = {};
+  try { data = JSON.parse(raw ?? '{}') ?? {}; } catch { data = {}; }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return [];
+  const out = [];
+  for (const [id, one] of Object.entries(data)) {
+    if (!/^[\w.-]{1,60}$/.test(id) || !one || typeof one !== 'object' || !Array.isArray(one.env) || one.env.length !== 1) continue;
+    out.push({ id, label: typeof one.name === 'string' && one.name.trim() ? one.name.trim().slice(0, 60) : id, docUrl: typeof one.doc === 'string' && /^https:\/\//.test(one.doc) ? one.doc : null });
+  }
+  return out;
+}
+// Every provider a key can be pasted for: MADRE's own four first (their key pages), then the
+// catalogue's, each once, the popular ones marked.
+export async function openCodeKeyProviders({ home = homedir(), env = process.env } = {}) {
+  const catalog = await readOpenCodeCatalog({ home, env });
+  const byId = new Map(OPENCODE_PROVIDERS.map((one) => [one.id, { ...one, featured: true }]));
+  for (const one of catalog) if (!byId.has(one.id)) byId.set(one.id, { id: one.id, label: one.label, keyUrl: one.docUrl, featured: OPENCODE_FEATURED.includes(one.id) });
+  const rank = (one) => { const at = OPENCODE_FEATURED.indexOf(one.id); return at < 0 ? Infinity : at; };
+  return [...byId.values()].sort((a, b) => Number(b.featured) - Number(a.featured) || rank(a) - rank(b));
+}
+
 // What the room offers for each agent that cannot be signed in with a click.
 export function keyPlanFor(id) {
+  if (id === 'claude') {
+    return {
+      agent: 'claude',
+      label: 'Anthropic API key',
+      keyUrl: 'https://console.anthropic.com/settings/keys',
+      writesTo: '~/.claude/settings.json',
+      // Said plainly because it is true: this file is the Claude CLI's own, not MADRE's. A key
+      // there is the one every Claude Code on this computer will use, MADRE's turns included.
+      note: 'The key is written where the Claude CLI looks for it, readable only by you. MADRE keeps no copy. It becomes the account Claude Code uses on this computer, here and in your own terminal, until you remove it.',
+      providers: null,
+    };
+  }
   if (id === 'gemini') {
     return {
       agent: 'gemini',
@@ -99,9 +139,36 @@ async function applyGeminiKey(key, { home, probe }) {
   }
 }
 
+// ---- Claude: `env.ANTHROPIC_API_KEY` in its own settings, confirmed by `claude auth status`.
+// The CLI reads that env block before it runs, which is why a key there is a session: its own
+// status answers `api_key` afterwards. Everything else in the file is left as it was.
+async function applyClaudeKey(key, { home, probe }) {
+  const dir = join(home, '.claude');
+  const file = join(dir, 'settings.json');
+  await mkdir(dir, { recursive: true });
+  const before = await readIfThere(file);
+  try {
+    let settings = {};
+    try { settings = JSON.parse(before ?? '{}') ?? {}; } catch { settings = {}; }
+    if (typeof settings !== 'object' || Array.isArray(settings)) settings = {};
+    settings.env = { ...(settings.env ?? {}), ANTHROPIC_API_KEY: key };
+    await writeFile(file, `${JSON.stringify(settings, null, 2)}\n`, { mode: OWNER_ONLY });
+    await chmod(file, OWNER_ONLY).catch(() => {});
+    const state = await probe();
+    if (state?.state !== 'signed-in') {
+      await restore(file, before);
+      return { ok: false, error: `The key was written but Claude still reads as ${state?.state ?? 'unknown'}${state?.detail ? ` (${state.detail})` : ''}. Nothing was changed.` };
+    }
+    return { ok: true, detail: state.detail ?? 'via API key' };
+  } catch (error) {
+    await restore(file, before);
+    return { ok: false, error: `The key could not be written: ${error.message}` };
+  }
+}
+
 // ---- OpenCode: an entry in its auth.json, confirmed by asking `opencode auth list`.
 async function applyOpenCodeKey(key, { home, provider, executable, run }) {
-  const known = OPENCODE_PROVIDERS.some((item) => item.id === provider);
+  const known = typeof provider === 'string' ? (await openCodeKeyProviders({ home })).find((item) => item.id === provider) : null;
   if (!known) return { ok: false, error: 'Pick the provider this key belongs to.' };
   const file = join(home, '.local', 'share', 'opencode', 'auth.json');
   await mkdir(join(home, '.local', 'share', 'opencode'), { recursive: true });
@@ -114,8 +181,9 @@ async function applyOpenCodeKey(key, { home, provider, executable, run }) {
     await chmod(file, OWNER_ONLY).catch(() => {});
     // OpenCode itself is the judge: if its own listing does not show the provider, the shape
     // MADRE wrote is not the shape it reads, and nothing should be left behind.
-    const listed = await run(executable, ['auth', 'list']);
-    if (!new RegExp(provider, 'i').test(listed)) {
+    // It lists the provider by its name («Together AI»), sometimes by its id.
+    const listed = String(await run(executable, ['auth', 'list'])).toLowerCase();
+    if (!listed.includes(provider.toLowerCase()) && !listed.includes(String(known.label).toLowerCase())) {
       await restore(file, before);
       return { ok: false, error: `OpenCode does not list ${provider} after the key was written, so MADRE put the file back. Run \`opencode auth login\` in a terminal for this one.` };
     }
@@ -139,7 +207,48 @@ const runOpenCode = async (executable, args) => {
 export async function applyKey({ agent, key, provider = null, home = homedir(), probe, executable = 'opencode', run = runOpenCode }) {
   const checked = normalizeKey(key);
   if (!checked.ok) return checked;
+  if (agent === 'claude') return applyClaudeKey(checked.key, { home, probe });
   if (agent === 'gemini') return applyGeminiKey(checked.key, { home, probe });
   if (agent === 'opencode') return applyOpenCodeKey(checked.key, { home, provider, executable, run });
   return { ok: false, error: `${agent} does not take a key here: it signs in with a click.` };
 }
+
+// ---- OpenCode's providers, as its auth.json says them: who is signed in and how, never the key.
+// `api` is a key (MADRE's or one pasted in a terminal), `oauth` an account signed in from
+// `opencode auth login`. Anything unreadable reads as nobody.
+export async function readOpenCodeProviders({ home = homedir() } = {}) {
+  const raw = await readIfThere(join(home, '.local', 'share', 'opencode', 'auth.json'));
+  let auth = {};
+  try { auth = JSON.parse(raw ?? '{}') ?? {}; } catch { auth = {}; }
+  if (!auth || typeof auth !== 'object' || Array.isArray(auth)) return [];
+  return Object.entries(auth)
+    .filter(([id, entry]) => /^[\w.-]{1,60}$/.test(id) && entry && typeof entry === 'object')
+    .map(([id, entry]) => ({ id, type: entry.type === 'api' || entry.type === 'oauth' ? entry.type : 'other' }));
+}
+
+// Takes a provider's key out of OpenCode's auth.json, the other entries untouched. Only a key
+// (`api`): an account signed in with OpenCode's own login is signed out where it was signed in.
+// OpenCode is the judge again: if it still lists the provider, the file goes back as it was.
+export async function removeOpenCodeKey({ provider, home = homedir(), executable = 'opencode', run = runOpenCode } = {}) {
+  if (typeof provider !== 'string' || !/^[\w.-]{1,60}$/.test(provider)) return { ok: false, error: 'Pick the provider whose key goes.' };
+  const file = join(home, '.local', 'share', 'opencode', 'auth.json');
+  const before = await readIfThere(file);
+  let auth = {};
+  try { auth = JSON.parse(before ?? '{}') ?? {}; } catch { return { ok: false, error: 'OpenCode\'s auth.json could not be read, so nothing was changed.' }; }
+  if (!auth[provider]) return { ok: false, error: `OpenCode has no key for ${provider}.` };
+  if (auth[provider].type !== 'api') return { ok: false, error: `${provider} is signed in with its account, not a key: sign it out with \`opencode auth logout\` in a terminal.` };
+  try {
+    delete auth[provider];
+    await writeFile(file, `${JSON.stringify(auth, null, 2)}\n`, { mode: OWNER_ONLY });
+    await chmod(file, OWNER_ONLY).catch(() => {});
+    const listed = await run(executable, ['auth', 'list']);
+    if (new RegExp(`\\b${provider.replace(/[.-]/g, '\\$&')}\\b`, 'i').test(listed.replace(/auth\.json/gi, ''))) {
+      await restore(file, before);
+      return { ok: false, error: `OpenCode still lists ${provider}, so MADRE put the file back. Remove it with \`opencode auth logout\` in a terminal.` };
+    }
+    return { ok: true };
+  } catch (error) {
+    await restore(file, before);
+    return { ok: false, error: `The key could not be removed: ${error.message}` };
+  }
+}

package/src/dataset.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // The dataset behind MADRE AI: every exchange the room kept (never GHOST),
 // redacted, as chat pairs a small model can learn from, plus the distilled
 // notes. Written next to the room's ledger in the format mlx-lm and most

package/src/directives.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Agent-to-agent delegation. An agent answering in the room may end its reply
 // with a fenced block that puts other agents to work, in order:
 //
@@ -9,9 +11,9 @@
 //
 // MADRE runs the steps sequentially as regular room turns, each recorded,
 // each subject to handoff, budget and timeout, and each stoppable by the
-// human. A step addressed to the orchestrator itself becomes its closing
-// turn once the others have answered. Delegated agents cannot delegate
-// further (depth is capped at one), so a plan always terminates.
+// human. The orchestrator gets a closing turn after the others have answered.
+// Delegated agents cannot delegate further (depth is capped at one); the
+// orchestrator may start another bounded wave after reviewing their results.
 
 export const DELEGATION_HELP = (self, others, maxSteps) => [
   `You may put other agents to work: ${others.map((id) => `@${id}`).join(', ')}.`,
@@ -21,8 +23,8 @@ export const DELEGATION_HELP = (self, others, maxSteps) => [
   `@${others[0] ?? 'codex'}: <question for that agent>`,
   `@${self}: <what you will do with their answers, optional closing turn for you>`,
   '```',
-  'A step may name the mode it needs, "@codex #2: create the page" or "@claude #3: fix the router"; MADRE caps it at your own mode and at that agent\'s MAX MODE. Without a number a step inherits the plan\'s mode.',
-  `MADRE runs the steps in order (at most ${maxSteps}), shows every answer in the room, then hands you the closing turn if you asked for one.`,
+  'A step may name the mode it needs, "@codex #2: create the page" or "@claude #3: fix the router"; MADRE uses the human permission for this turn as the ceiling. A higher mode pauses for the human to unlock it for that agent, and #4 always does. Without a number a step only reads, or creates files when the plan may create; ask for #3 by name.',
+  `MADRE runs the steps in order (at most ${maxSteps}), shows every answer in the room, then hands you a closing turn to review progress. If work remains within the human permission, you may end that turn with another pulse plan; at most three waves run from one request.`,
   'The plan block must be the very last thing in your reply: nothing after it, not even a closing sentence. Say everything else before it.',
   'Address each agent once. Do not delegate what you can answer yourself.',
 ].join('\n');
@@ -47,7 +49,7 @@ export function parseDirectives(text, { self, available = [], maxSteps = 4 } = {
       const line = raw.trim();
       if (!line || line.startsWith('#')) continue;
       // "@agent: text" or "@agent #2: text": the mode is a request, capped by the plan's ceiling and the agent's MAX MODE.
-      const match = line.match(/^[-*]?\s*@([a-z0-9_-]+)\s*(?:#([0-3]))?\s*[:：]\s*(.+)$/i);
+      const match = line.match(/^[-*]?\s*@([a-z0-9_-]+)\s*(?:#([0-4]))?\s*[:：]\s*(.+)$/i);
       if (!match) { ignored.push({ line, reason: 'not a step (expected "@agent: text" or "@agent #2: text")' }); continue; }
       const agent = match[1].toLowerCase();
       const instruction = match[3].trim();

package/src/distiller.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // The archivist's turn: every so often the cheapest agent in the room reads
 // the exchanges nobody has distilled yet and writes the few notes worth
 // keeping for every later turn. Pure functions here; the room schedules and

package/src/embeddings.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Embeddings for the room memory: meaning-aware recall on top of the lexical
 // index. Gemini's embedding model through the user's own key (the same key
 // Image Studio and the Gemini CLI use); no key, no embeddings, and recall stays

package/src/enlaces.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Links between rooms (docs/MACROVERSO.md, phase 3b): the contract two rooms sign, the key that
 // proves a caller is a MADRE process on this Mac, the side that asks, and the counters of what
 // crossed. A link reads; nothing here writes in another room.
@@ -108,7 +110,7 @@ export function normalizeContract(raw, { now = new Date(), salas = null } = {})
   if (!Array.isArray(raw.kinds) || !raw.kinds.length) fail('A connection names the kinds that may cross.');
   const kinds = [...new Set(raw.kinds.map(String))];
   for (const kind of kinds) {
-    if (kind === 'aberration') fail('An aberration never crosses a connection.');
+    if (kind === 'aberration') fail('A doubtful memory never crosses a connection.');
     if (!LINK_KINDS.includes(kind)) fail(`"${kind}" is not a kind of memory.`);
   }
   kinds.sort((x, y) => LINK_KINDS.indexOf(x) - LINK_KINDS.indexOf(y));
@@ -124,7 +126,7 @@ export function normalizeContract(raw, { now = new Date(), salas = null } = {})
   const revoked = isoOrNull(raw.revoked, 'revoked');
   // Fase 3e: the room that reads also gets, on each turn, up to RECALL_NOTES of these notes without
   // asking. Off unless the human ticks it; a reading like any other, counted against `perHour`.
-  if (raw.recall !== undefined && raw.recall !== null && typeof raw.recall !== 'boolean') fail('recall is on or off.');
+  if (raw.recall !== undefined && raw.recall !== null && typeof raw.recall !== 'boolean') fail('automatic recall can only be on or off.');
   const recall = raw.recall === true;
 
   const orders = raw.orders && typeof raw.orders === 'object' ? raw.orders : {};
@@ -136,8 +138,8 @@ export function normalizeContract(raw, { now = new Date(), salas = null } = {})
   const allowed = Boolean(orders.allowed);
   if (salas) {
     const serves = direction === 'both' ? [a, b] : direction === 'a→b' ? [a] : [b];
-    if (serves.includes(salas)) fail('The Coordinator\'s project never serves a connection: the Coordinator gathers every project and is nobody\'s source.');
-    if (allowed && a !== salas && b !== salas) fail('Orders need the Coordinator\'s project at one end of the connection.');
+    if (serves.includes(salas)) fail('The Coordinator never shares through a connection: it gathers every project and is nobody\'s source.');
+    if (allowed && a !== salas && b !== salas) fail('Orders need the Coordinator at one end of the connection.');
   }
 
   // Who signed it (D-S13): the human always may; BISHOP only a link to read, with no orders, that

package/src/event-store.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';

package/src/exam.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // The three tests that answer "is this room ready to be developed with?"
 //
 // The maturity reading counts what the archive is made of. It cannot tell you whether the archive
@@ -174,9 +176,9 @@ export function consistencyExam({ findings = [], notes = [], now = Date.now() }
     open, refuted, standing: standing.length, aberrations: aberrations.length, trend,
     passed,
     says: open
-      ? t('EYECAT is holding {n} contradictions nobody has settled.', { n: open })
+      ? (open === 1 ? t('The memory reviewer found 1 contradiction nobody has settled.') : t('The memory reviewer found {n} contradictions nobody has settled.', { n: open }))
       : trend === 'rising'
-        ? t('Nothing is open, but aberrations are being filed more often lately than they used to be.')
+        ? t('Nothing is open, but doubtful memories are being filed more often lately than they used to be.')
         : t('Nothing contradicts anything: {standing} notes stand, {refuted} were taken out of circulation.', { standing: standing.length, refuted }),
   };
 }
@@ -231,9 +233,9 @@ export function saysFor(result) {
   }
   if (result.id === 'consistency' && Number.isFinite(result.open)) {
     return result.open
-      ? t('EYECAT is holding {n} contradictions nobody has settled.', { n: result.open })
+      ? (result.open === 1 ? t('The memory reviewer found 1 contradiction nobody has settled.') : t('The memory reviewer found {n} contradictions nobody has settled.', { n: result.open }))
       : result.trend === 'rising'
-        ? t('Nothing is open, but aberrations are being filed more often lately than they used to be.')
+        ? t('Nothing is open, but doubtful memories are being filed more often lately than they used to be.')
         : t('Nothing contradicts anything: {standing} notes stand, {refuted} were taken out of circulation.', { standing: result.standing, refuted: result.refuted });
   }
   return result.says ?? null;

package/src/extensions.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 import { spawn } from 'node:child_process';
 import { MODULES, moduleById, describeModules } from './modules/index.mjs';
 export { gitToplevel, findOnPath } from './modules/helpers.mjs';
@@ -25,38 +27,59 @@ export async function listExtensions({ projectRoot, agents = [], config = {}, im
 // Runs one installer inside the project, streaming output lines. `runner`
 // lets tests substitute the real installer with a local script.
 // `npm` and other Node CLIs are .cmd shims on Windows, which cannot be spawned directly.
-export function runInstaller({ command, args, projectRoot, onLine, timeoutMs = 600000, heartbeatMs = 8000, env = process.env }) {
+//
+// A sign-in is the same spawn with a human in the middle of it, so three knobs exist for it:
+// `stdin: 'pipe'` opens a way back in (a CLI that asks for a pasted code reads it there),
+// `onChild` hands the caller that way in, and `flushIdleMs` emits a line that never ends in a
+// newline — a prompt like `Paste code here > ` — once the output has been still for that long.
+// Without it the prompt sits in the buffer and the room shows a sign-in that says nothing.
+export function runInstaller({ command, args, projectRoot, onLine, timeoutMs = 600000, heartbeatMs = 8000, env = process.env, stdin = 'ignore', onChild = null, flushIdleMs = 0, quietNote = 'installer is quiet (npm install or git status can take a while)' }) {
   return new Promise((resolve) => {
-    const child = spawn(command, args, { cwd: projectRoot, env: { ...env, NO_COLOR: '1', CI: '1' }, stdio: ['ignore', 'pipe', 'pipe'], shell: process.platform === 'win32', windowsHide: true });
+    const child = spawn(command, args, { cwd: projectRoot, env: { ...env, NO_COLOR: '1', CI: '1' }, stdio: [stdin, 'pipe', 'pipe'], shell: process.platform === 'win32', windowsHide: true });
     const started = Date.now();
     let lastOutput = started;
+    let buffer = '';
+    const emit = (line, stream) => { lastOutput = Date.now(); onLine?.(line, stream); };
     // Installers go quiet for long stretches (npm install, git status); say so.
     const heartbeat = setInterval(() => {
+      // A half-line waiting on a human is said before the silence is reported, so the room shows
+      // the question instead of the heartbeat that would otherwise be the only thing on screen.
+      if (flushIdleMs && buffer.trim() && Date.now() - lastOutput >= flushIdleMs) { const partial = buffer.trim(); buffer = ''; emit(partial, 'stdout'); return; }
       if (Date.now() - lastOutput >= heartbeatMs) {
-        onLine?.(`… still running · ${Math.round((Date.now() - started) / 1000)}s · installer is quiet (npm install or git status can take a while)`, 'heartbeat');
+        onLine?.(`… still running · ${Math.round((Date.now() - started) / 1000)}s · ${quietNote}`, 'heartbeat');
         lastOutput = Date.now();
       }
-    }, Math.min(heartbeatMs, 2000));
+    }, Math.min(flushIdleMs || heartbeatMs, heartbeatMs, 2000));
     heartbeat.unref?.();
-    let buffer = '';
     const feed = (chunk, stream) => {
       buffer += chunk;
       let index;
       while ((index = buffer.indexOf('\n')) >= 0) {
         const line = buffer.slice(0, index).replace(/\r$/, '');
         buffer = buffer.slice(index + 1);
-        if (line.trim()) { lastOutput = Date.now(); onLine?.(line, stream); }
+        if (line.trim()) emit(line, stream);
       }
     };
     child.stdout.on('data', (chunk) => feed(String(chunk), 'stdout'));
     child.stderr.on('data', (chunk) => feed(String(chunk), 'stderr'));
     const timer = setTimeout(() => { child.kill('SIGKILL'); }, timeoutMs);
-    child.on('error', (error) => { clearTimeout(timer); clearInterval(heartbeat); resolve({ code: 1, error: error.code === 'ENOENT' ? `${error.message} (is the project folder present and ${command} on PATH?)` : error.message }); });
+    let done = false;
+    const settle = (result) => { if (done) return; done = true; clearTimeout(timer); clearInterval(heartbeat); resolve(result); };
+    onChild?.({
+      // What the room can do to a sign-in while it runs: answer it, or call it off.
+      write: (text) => { try { child.stdin?.write(text); return true; } catch { return false; } },
+      cancel: () => {
+        try { child.kill('SIGTERM'); } catch { /* already gone */ }
+        // A terminal UI can ignore a polite ask; it does not get to ignore the second one.
+        const hard = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, 1500);
+        hard.unref?.();
+      },
+      pid: child.pid ?? null,
+    });
+    child.on('error', (error) => settle({ code: 1, error: error.code === 'ENOENT' ? `${error.message} (is the project folder present and ${command} on PATH?)` : error.message }));
     child.on('close', (code) => {
-      clearTimeout(timer);
-      clearInterval(heartbeat);
       if (buffer.trim()) onLine?.(buffer.trim(), 'stdout');
-      resolve({ code: code ?? 1 });
+      settle({ code: code ?? 1 });
     });
   });
 }

package/src/eyecat-watch.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // EYECAT, as the room runs it. The judgement lives in eyecat.mjs; this schedules it, picks who
 // may answer, and puts what comes back in front of the human.
 //

package/src/eyecat.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // EYECAT: the watcher that asks whether the room still believes what it wrote down.
 //
 // Pure functions here. Nothing in this file talks to a model, reads a file or touches the room;

package/src/file-ops.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Copying and moving a file, from the human's own hands.
 //
 // Everything else in MADRE that writes into a project is an agent under a permission mode. This

package/src/files.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, readdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import { dirname, extname, join, resolve, sep } from 'node:path';
@@ -96,6 +98,36 @@ export async function walkProject(root, { maxFiles = 20000, ttlMs = 15000 } = {}
   return files;
 }
 
+// What changed on disk since a moment, by modification time (2026-10-14). A restore point sees
+// only what git sees, so a PDF a command wrote into an ignored `output/` was there and nobody said
+// so: the Finder did not refresh and nothing told whose it was. This looks at the files
+// themselves, skipping the same heavy folders the search skips and MADRE's own `.pulse`/`.madre`,
+// bounded so a large project costs a fraction of a second. Newest first.
+const UNWATCHED = new Set([...SHALLOW, '.pulse', '.madre']);
+export async function filesChangedSince(root, since, { maxFiles = 8000, limit = 40 } = {}) {
+  const from = Number(since) - 250;
+  if (!Number.isFinite(from)) return [];
+  const found = [];
+  let seen = 0;
+  async function walk(dir, prefix, depth) {
+    if (seen >= maxFiles || depth > 14) return;
+    let entries = [];
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    const files = [];
+    for (const entry of entries) {
+      if (SKIP.has(entry.name)) continue;
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) { if (!UNWATCHED.has(entry.name)) await walk(join(dir, entry.name), rel, depth + 1); continue; }
+      if (entry.isFile()) files.push(rel);
+    }
+    seen += files.length;
+    const stats = await Promise.all(files.map((rel) => stat(join(root, rel)).then((info) => [rel, info.mtimeMs], () => null)));
+    for (const one of stats) if (one && one[1] >= from) found.push({ path: one[0], at: one[1] });
+  }
+  await walk(root, '', 0);
+  return found.sort((a, b) => b.at - a.at).slice(0, limit).map((one) => one.path);
+}
+
 export function scoreFile(path, query) {
   const q = query.toLowerCase();
   if (!q) return 1;

package/src/github.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // GitHub, as the GITHUB module and its MCP server both speak to it.
 //
 // Two ways in, and the order matters. First the `gh` CLI, if this computer has it and it is

package/src/heartbeat.mjs

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
+// «Still in use»: once a day, every copy of MADRE tells madre.run it is on (2026-10-13).
+//
+// What goes, and nothing else: a random identifier this copy made for itself once
+// (~/.pulse/install-id, from crypto.randomUUID — derived from nothing about the person or the
+// machine), the MADRE version, the system (darwin, linux, win32) and Node's major version. No
+// name, no email, no project, no path, no agent, nothing said in a room. madre.run keeps no IP
+// (functions/api/ping.js of the landing). It is how the author knows how many people use MADRE,
+// which versions they run and whether they come back — what npm's download count cannot say.
+//
+// It is said in docs/REFERENCE.md › «Lo que sale de la máquina» and on madre.run, and it goes
+// through the same fetch every other outbound request does, so the room's own list of what left
+// the machine shows it. Offline or behind a firewall it fails in silence and is tried again
+// later: MADRE never waits on it. PULSE_HEARTBEAT_URL points it elsewhere, for development and
+// for the test suite, which must never reach madre.run.
+
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const HEARTBEAT_URL = 'https://madre.run/api/ping';
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+export async function installId(root) {
+  const file = join(root, 'install-id');
+  const kept = (await readFile(file, 'utf8').catch(() => '')).trim();
+  if (ID.test(kept)) return kept;
+  const made = randomUUID();
+  await mkdir(root, { recursive: true });
+  await writeFile(file, `${made}\n`, { mode: 0o600 });
+  return made;
+}
+
+// What the request carries: built here, in one place, so a test can say exactly what leaves.
+export const heartbeatBody = ({ id, version, platform = process.platform, node = process.versions.node }) => ({
+  id, version, os: ['darwin', 'linux', 'win32'].includes(platform) ? platform : 'other', node: String(node).split('.')[0],
+});
+
+// Once per UTC day per copy, whichever of its processes gets there first; a day that failed is
+// tried again on the next call.
+export async function heartbeat({ root, version, fetchImpl = globalThis.fetch, url = process.env.PULSE_HEARTBEAT_URL ?? HEARTBEAT_URL, now = new Date() }) {
+  const day = now.toISOString().slice(0, 10);
+  const stamp = join(root, 'heartbeat.json');
+  try {
+    if (JSON.parse(await readFile(stamp, 'utf8')).day === day) return { sent: false, reason: 'today' };
+  } catch { /* never sent, or unreadable: send */ }
+  try {
+    const body = heartbeatBody({ id: await installId(root), version });
+    const response = await fetchImpl(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(5000) });
+    if (!response.ok) return { sent: false, reason: `HTTP ${response.status}` };
+    await writeFile(stamp, `${JSON.stringify({ day })}\n`);
+    return { sent: true, body };
+  } catch (error) {
+    return { sent: false, reason: error?.message ?? 'unreachable' };
+  }
+}

package/src/i18n.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // The room's language, on this side of the wire.
 //
 // The catalogue is the page's: public/es.js, one file for the whole product, because a sentence
@@ -24,9 +26,21 @@ export function setLanguage(id) {
   return current;
 }
 
+// «Mac» only on a Mac (2026-10-15): MADRE installs on Linux too, and a sentence about the machine
+// it runs on says «computer» there. Same rule as public/i18n.js (hostWords); hardware named on
+// purpose («a Mac with an M chip») has no article in front and is left alone.
+let hostIsMac = process.platform === 'darwin';
+export const setHostIsMac = (value) => { hostIsMac = Boolean(value); return hostIsMac; };
+export function hostWords(text) {
+  if (hostIsMac || typeof text !== 'string' || !text.includes('Mac')) return text;
+  return text
+    .replace(/\b(this|your|the|This|Your|The) Mac\b/g, '$1 computer')
+    .replace(/(^|[^\p{L}])(esta|tu|la|Esta|Tu|La) Mac\b/gu, '$1$2 computadora');
+}
+
 export function t(text, vars = null) {
   if (typeof text !== 'string' || !text) return text;
-  const said = CATALOGUES[current]?.[text] ?? text;
+  const said = hostWords(CATALOGUES[current]?.[text] ?? text);
   if (!vars) return said;
   return said.replace(/\{(\w+)\}/g, (whole, name) => (Object.hasOwn(vars, name) ? String(vars[name]) : whole));
 }

package/src/image-studio.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 import { fileURLToPath } from 'node:url';
 import { resolveGeminiKey } from './mcp/image-server.mjs';
 

package/src/json-file.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // Small files that more than one thing changes at once (2026-10-12, Lote 2 of the 1.0 review): the
 // tour, the review ask, a project's record of where it is, the list of a room's conversations.
 // Each was read, changed and written with nothing between two changes, so the second one wrote

package/src/launch.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 // What is shown of a command, and what is never shown.
 //
 // THE LAUNCH floor in the core prints the exact command MADRE would run, because a person who is