@jossuealcala/madre 0.7.2 → 1.0.1

package/src/heartbeat.mjs

@@ -0,0 +1,55 @@
+// «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/json-file.mjs

@@ -0,0 +1,63 @@
+// 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
+// over the first — a rename lost to a message arriving, a chapter read lost to a tab saying it
+// held the tour — and the drafts had a name per process, so two writes from the same room fought
+// over one draft and one of them failed.
+//
+// `writeWhole` writes a file whole: a draft with a name of its own, renamed over it, so nobody
+// ever reads half of one. `oneAtATime` runs one change of a file at a time: in this process by a
+// queue, and between the rooms of this Mac by a lock file beside it, as config.json is kept
+// (src/config.mjs). A lock left by a process that died is stale after a few seconds.
+
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+export async function writeWhole(file, text, { mode } = {}) {
+  await mkdir(dirname(file), { recursive: true });
+  const draft = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(draft, text, mode ? { mode } : undefined);
+    await rename(draft, file);
+  } catch (error) {
+    await rm(draft, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+const STALE_MS = 5000;
+async function lockBeside(file) {
+  const lock = `${file}.lock`;
+  await mkdir(dirname(lock), { recursive: true });
+  for (let attempt = 0; attempt < 250; attempt += 1) {
+    try {
+      await (await open(lock, 'wx')).close();
+      return () => rm(lock, { force: true });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const since = await stat(lock).catch(() => null);
+      if (since && Date.now() - since.mtimeMs > STALE_MS) { await rm(lock, { force: true }); continue; }
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+  }
+  throw new Error(`${file} is being changed by another room; try again.`);
+}
+
+const queues = new Map();
+export function oneAtATime(file, work) {
+  const run = async () => {
+    const release = await lockBeside(file);
+    try {
+      return await work();
+    } finally {
+      await release();
+    }
+  };
+  const before = queues.get(file) ?? Promise.resolve();
+  const turn = before.then(run, run);
+  const settled = turn.catch(() => {});
+  queues.set(file, settled);
+  void settled.then(() => { if (queues.get(file) === settled) queues.delete(file); });
+  return turn;
+}

package/src/lease.mjs

@@ -1,6 +1,6 @@
 import { mkdir, readdir, realpath, stat } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
-import { contentTypeFor } from './files.mjs';
+import { declaredTypeFor } from './files.mjs';
 
 // A creation lease is the human saying, for one message (and the plan it may
 // start): "these agents may create files, here". MADRE makes a fresh
@@ -90,7 +90,7 @@ export function diffSnapshots(before, after, { relativeDir }) {
       name: name.split('/').pop(),
       path: `${relativeDir.split(sep).join('/')}/${name}`,
       size: info.size,
-      contentType: contentTypeFor(name),
+      contentType: declaredTypeFor(name),
       status: previous ? 'changed' : 'created',
     });
   }

package/src/lobby-work.mjs

@@ -0,0 +1,103 @@
+// What was worked on last on this Mac, for the lobby (2026-10-10): the newest conversations of
+// every room the lobby knows, open or asleep, each with its last few lines, and the summary MADRE
+// writes of them with its local model. Everything here READS: a room's list of conversations
+// (chats.json) and the end of a conversation's ledger, from the room's folder, never asking the
+// room and never writing to it. The summary is checked against what it was given: a line that does
+// not carry the number of a conversation it was given is dropped, and the project of each line is
+// put by the lobby, from that number, never taken from the model's words.
+
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { chatLedger, listChats } from './chats.mjs';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+// The last messages of one conversation, read from the end of its ledger without reading all of
+// it (a ledger also carries quota readings and turns, and grows for months). A cut first line is
+// dropped; a line that is not a message is passed over; delegations between agents are the
+// plan's own bookkeeping, not what was said.
+export async function lastMessages(file, { limit = 4, window = 512 * 1024, maxChars = 360 } = {}) {
+  let handle = null;
+  try {
+    handle = await open(file, 'r');
+    const { size } = await handle.stat();
+    const start = Math.max(0, size - window);
+    const buffer = Buffer.alloc(size - start);
+    await handle.read(buffer, 0, buffer.length, start);
+    const lines = buffer.toString('utf8').split('\n');
+    if (start > 0) lines.shift();
+    const said = [];
+    for (let index = lines.length - 1; index >= 0 && said.length < limit; index -= 1) {
+      if (!lines[index].includes('"message.created"')) continue;
+      let event = null;
+      try { event = JSON.parse(lines[index]); } catch { continue; }
+      const payload = event?.payload ?? {};
+      if (event?.type !== 'message.created' || payload.status === 'delegated') continue;
+      // Read as words: without the marks a message is written in (bold, code, headings, links).
+      const text = String(payload.text ?? '').replace(/```[\s\S]*?```/g, ' ').replace(/\[([^\]]+)\]\([^)]+\)/g, '$1').replace(/(\*\*|__|`)/g, '').replace(/^#+\s*/gm, '').replace(/\s+/g, ' ').trim();
+      if (!text) continue;
+      const person = payload.role === 'user' || payload.sender === 'human';
+      said.unshift({ who: person ? 'person' : String(payload.sender ?? 'agent'), text: text.slice(0, maxChars), at: event.timestamp ?? null });
+    }
+    return said;
+  } catch {
+    return [];
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+// The newest conversations across the rooms, at most `perRoom` from each and `limit` in all, from
+// the last `days` days; each with its last lines. `rooms` is [{ id, name }] as the lobby names them.
+export async function recentWork({ stateRoot, rooms, now = Date.now(), days = 14, limit = 6, perRoom = 2 }) {
+  const since = now - days * DAY_MS;
+  const found = [];
+  for (const room of rooms) {
+    const dir = join(stateRoot, 'rooms', room.id);
+    const { chats } = await listChats(dir).catch(() => ({ chats: [] }));
+    const fresh = chats.filter((chat) => chat.messages > 0 && Date.parse(chat.updatedAt ?? 0) >= since).slice(0, perRoom);
+    for (const chat of fresh) found.push({ room: room.id, name: room.name, chat: chat.id, title: chat.title, at: chat.updatedAt, messages: chat.messages });
+  }
+  found.sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
+  const newest = found.slice(0, limit);
+  for (const item of newest) item.said = await lastMessages(chatLedger(join(stateRoot, 'rooms', item.room), item.chat));
+  return newest;
+}
+
+// What MADRE is told: who it is writing for, one line per numbered conversation, and that it may
+// only say what that conversation says. It never names the project: the lobby puts the name to
+// each line by its number, so a small local model cannot give one project's work to another.
+export const WORK_SYSTEM = {
+  es: 'Eres MADRE. Resumes para la persona lo último que se trabajó. Recibes conversaciones numeradas (#1, #2…). Para cada una escribe UNA línea con el formato `#número: frase`, en el mismo orden. La frase, corta y en pasado, dice qué se hizo o se decidió en ESA conversación y, si lo hay, qué quedó pendiente; si no queda claro, di de qué trata. Usa solo lo que dice esa conversación: no mezcles conversaciones ni inventes nombres, cifras o conclusiones. No escribas nada más.',
+  en: 'You are MADRE. You summarise for the person what was worked on last. You get numbered conversations (#1, #2…). For each one write ONE line in the form `#number: sentence`, in the same order. The sentence, short and in the past tense, says what was done or decided in THAT conversation and, if there is one, what was left pending; if it is not clear, say what it is about. Use only what that conversation says: do not mix conversations or invent names, figures or conclusions. Write nothing else.',
+};
+export function workPrompt(items, language = 'es') {
+  const person = language === 'es' ? 'Persona' : 'Person';
+  return items.map((item, index) => {
+    const lines = (item.said ?? []).map((one) => `  ${one.who === 'person' ? person : `@${one.who}`}: ${one.text}`);
+    return [`#${index + 1} · «${item.title}»`, ...lines].join('\n');
+  }).join('\n\n');
+}
+
+// The answer, as lines the lobby can show: each must carry the number of a conversation it was
+// given, once; the project is that conversation's, never a word of the model's.
+export function parseWork(text, items, { max = 5 } = {}) {
+  const seen = new Set();
+  const bullets = [];
+  for (const raw of String(text ?? '').split('\n')) {
+    const line = raw.replace(/\*\*/g, '').replace(/^\s*(?:[-*•·]\s*)?/, '').trim();
+    const match = /^#?\s*(\d{1,2})\s*[:.)\-–—]\s*(.+)$/.exec(line);
+    if (!match) continue;
+    const index = Number(match[1]) - 1;
+    const item = items[index];
+    if (!item || seen.has(index)) continue;
+    const said = match[2].replace(/^[«"“]|[»"”]$/g, '').trim();
+    // A line that only says the conversation's name again says nothing about the work.
+    const bare = (words) => String(words ?? '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+    if (said.length < 8 || bare(said) === bare(item.title)) continue;
+    seen.add(index);
+    bullets.push({ room: item.room, name: item.name, text: said.slice(0, 280) });
+    if (bullets.length >= max) break;
+  }
+  return bullets;
+}

package/src/local-ai.mjs

@@ -0,0 +1,48 @@
+// Which projects use the local AI (Ollama), decided from Home (2026-10-13).
+//
+// Ollama is one per computer and its switches live in ~/.pulse/config.json, which every project
+// shares: `modules.ollama` says whether the local AI is on at all and what it does (search by
+// meaning, summing up the memory, @madre). This adds the one thing that file could not say —
+// which projects — without touching any of that:
+//
+//   localAi.mode  'auto'   every project uses it, new ones too. Home decides; projects follow.
+//                 'pick'   only the projects switched on. New ones start without it.
+//                 'manual' each project decides in its own Settings. New ones start with it.
+//   localAi.rooms { <room id>: true | false } what was switched, from Home or from the project.
+//
+// With nothing written the mode is 'auto', which is what MADRE did before this existed. The
+// master switch (`modules.ollama.enabled`) still wins: off there is off everywhere. Home's own
+// room, the Coordinator's, is not a project and always follows the master switch.
+
+export const LOCAL_MODES = ['auto', 'pick', 'manual'];
+
+export function localAiConfig(config = {}) {
+  const raw = config.localAi ?? {};
+  const mode = LOCAL_MODES.includes(raw.mode) ? raw.mode : 'auto';
+  const rooms = {};
+  for (const [id, on] of Object.entries(raw.rooms ?? {})) if (typeof on === 'boolean') rooms[id] = on;
+  return { mode, rooms };
+}
+
+// What one project gets. `on`: whether it uses the local AI now; `chosen`: what this project's
+// switch says, before the master switch; `editable`: whether its switch can be moved (not in auto).
+export function localAiFor(config = {}, roomId = null, { home = false } = {}) {
+  const master = (config.modules?.ollama?.enabled ?? true) !== false;
+  const { mode, rooms } = localAiConfig(config);
+  if (home || !roomId) return { mode, master, chosen: true, on: master, editable: false, home: Boolean(home) };
+  const chosen = mode === 'auto' ? true : mode === 'pick' ? rooms[roomId] === true : rooms[roomId] ?? true;
+  return { mode, master, chosen, on: master && chosen, editable: mode !== 'auto' };
+}
+
+// The patch for config.json: the whole `localAi` block, because updateConfig merges one level
+// down and a partial `rooms` would drop the projects it does not name.
+export function localAiPatch(config = {}, { mode, rooms } = {}) {
+  const now = localAiConfig(config);
+  const next = { mode: LOCAL_MODES.includes(mode) ? mode : now.mode, rooms: { ...now.rooms } };
+  for (const [id, on] of Object.entries(rooms ?? {})) {
+    if (typeof id !== 'string' || !id || id.length > 200) continue;
+    if (typeof on === 'boolean') next.rooms[id] = on;
+    else if (on === null) delete next.rooms[id];
+  }
+  return { localAi: next };
+}

package/src/looks.mjs

@@ -0,0 +1,88 @@
+// How the person wants MADRE to look, once for every page (2026-10-12). Each project is its own
+// origin — another port — and Home is one more, so what a browser keeps for one is invisible to
+// the others: the dark theme chosen in Home left every project light. The choices live here, in
+// ~/.pulse/looks.json, beside tour.json and whats-new.json; every page reads them when it opens or
+// comes back into view, and writes them when the person changes one. The browser's own copy stays,
+// so a page paints in the last known look before it hears from here.
+//
+// Only what the pages share: the theme, the accent, the wallpaper and its dials, the bubbles and
+// the text of the conversation. How Home lays out its own cards stays in Home's browser.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { oneAtATime, writeWhole } from './json-file.mjs';
+
+const CHOICE = /^[a-z][a-z0-9-]{0,23}$/;
+const NUMBER = /^\d{1,3}$/;
+export const LOOK_KEYS = {
+  'pulse.theme': CHOICE,
+  'pulse.accent': CHOICE,
+  'pulse.wallpaper': CHOICE,
+  'pulse.wallpaper.style': CHOICE,
+  'pulse.wallpaper.veil': NUMBER,
+  'pulse.wallpaper.blur': NUMBER,
+  'pulse.bubbles': CHOICE,
+  'pulse.text': CHOICE,
+};
+const looksFile = (stateRoot) => join(stateRoot, 'looks.json');
+
+// A project may keep a wallpaper of its own (2026-10-13): the person said «only in this project».
+// It lives beside the shared looks, under `rooms`, by the room's id; every other look stays shared.
+const ROOM_ID = /^[\w .-]{1,120}$/;
+const readFileLooks = (stateRoot) => readFile(looksFile(stateRoot), 'utf8').then((text) => JSON.parse(text)).catch(() => null);
+function roomsOf(raw) {
+  const rooms = {};
+  for (const [id, own] of Object.entries(raw?.rooms ?? {})) {
+    if (ROOM_ID.test(id) && typeof own?.wallpaper === 'string' && CHOICE.test(own.wallpaper)) rooms[id] = { wallpaper: own.wallpaper };
+  }
+  return rooms;
+}
+
+// What is kept, read key by key: anything else in the file, or a value of the wrong shape, is not
+// a look. `null` for a key means the first value — the room as it always was. With `room`, that
+// project's own wallpaper comes back too, as `own`.
+export async function readLooks(stateRoot, { room = null } = {}) {
+  const raw = await readFileLooks(stateRoot);
+  const looks = {};
+  for (const [key, shape] of Object.entries(LOOK_KEYS)) {
+    const value = raw?.looks?.[key];
+    looks[key] = typeof value === 'string' && shape.test(value) ? value : null;
+  }
+  const answer = { looks, saved: Boolean(raw && typeof raw.looks === 'object') };
+  if (room) answer.own = roomsOf(raw)[room] ?? null;
+  return answer;
+}
+// Every project's own wallpaper, for Home's cards.
+export async function roomLooks(stateRoot) {
+  return roomsOf(await readFileLooks(stateRoot));
+}
+// A project's own wallpaper set, or taken away (`null`): it follows the shared one again.
+export function changeRoomLook(stateRoot, room, wallpaper) {
+  return oneAtATime(looksFile(stateRoot), async () => {
+    if (typeof room !== 'string' || !ROOM_ID.test(room)) return { error: 'room' };
+    if (wallpaper !== null && (typeof wallpaper !== 'string' || !CHOICE.test(wallpaper))) return { error: 'value' };
+    const raw = await readFileLooks(stateRoot);
+    const { looks } = await readLooks(stateRoot);
+    const rooms = roomsOf(raw);
+    if (wallpaper === null) delete rooms[room]; else rooms[room] = { wallpaper };
+    await writeWhole(looksFile(stateRoot), `${JSON.stringify({ looks, ...(Object.keys(rooms).length ? { rooms } : {}), at: new Date().toISOString() }, null, 2)}\n`);
+    return { own: rooms[room] ?? null };
+  });
+}
+
+// A change from a page: the keys it names, set or cleared. A key it does not know, or a value of
+// the wrong shape, refuses the whole change rather than half of it.
+export function changeLooks(stateRoot, patch, now = new Date()) {
+  return oneAtATime(looksFile(stateRoot), async () => {
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return { error: 'looks' };
+    for (const [key, value] of Object.entries(patch)) {
+      if (!Object.hasOwn(LOOK_KEYS, key)) return { error: 'key' };
+      if (value !== null && (typeof value !== 'string' || !LOOK_KEYS[key].test(value))) return { error: 'value' };
+    }
+    const { looks } = await readLooks(stateRoot);
+    Object.assign(looks, patch);
+    const rooms = roomsOf(await readFileLooks(stateRoot));
+    await writeWhole(looksFile(stateRoot), `${JSON.stringify({ looks, ...(Object.keys(rooms).length ? { rooms } : {}), at: new Date(now).toISOString() }, null, 2)}\n`);
+    return { looks, saved: true };
+  });
+}

package/src/maturity.mjs

@@ -36,13 +36,13 @@ export function maturity({ readiness = null, notes = [], links = [], stats = nul
       id: 'volume', label: t('HOW MUCH THERE IS'),
       value: round(share(pairs, VOLUME_TARGET)),
       detail: t('{pairs} of about {target} exchanges worth training on', { pairs, target: VOLUME_TARGET }),
-      next: t('Use the room. Nothing else fills this.'),
+      next: t('Use the project. Nothing else fills this.'),
     },
     {
       id: 'coverage', label: t('HOW MUCH OF IT GETS USED'),
       value: round(share(recalled, standing.length)),
       detail: t('{recalled} of {total} memories have been reached for at least once', { recalled, total: standing.length }),
-      next: t('Memories nobody has needed may be noise, or may simply not have come up yet. Ask the room about older decisions and see which ones answer.'),
+      next: t('Memories nobody has needed may be noise, or may simply not have come up yet. Ask the project about older decisions and see which ones answer.'),
     },
     {
       id: 'weave', label: t('HOW WOVEN IT IS'),
@@ -64,7 +64,7 @@ export function maturity({ readiness = null, notes = [], links = [], stats = nul
       // progress where there is none.
       value: pairs > 0 ? round(1 - Math.min(1, Math.max(0, (noteShare - 0.5) / 0.5))) : 0,
       detail: t('{share}% of the corpus is recall questions, {turns} exchanges are real work', { share: Math.round(noteShare * 100), turns }),
-      next: t('Recall pairs are made from notes and cost nothing, so they pile up. Work in the room to balance them.'),
+      next: t('Recall pairs are made from notes and cost nothing, so they pile up. Work in the project to balance them.'),
     },
     {
       id: 'upkeep', label: t('HOW CURRENT IT IS'),

package/src/mcp/github-server.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// MADRE GITHUB: a small MCP server (stdio, JSON-RPC 2.0) that lets an agent read the GitHub side
+// of this project — pull requests, issues, checks — and, in #4 AIRLOCK only, open a pull request,
+// open an issue or leave a comment. There is no MADRE in the middle: this process asks gh, or
+// GitHub's API with the human's token, and nothing else.
+//
+// Reading comes back; writing does not. A comment carries the human's name the moment it lands,
+// so three things hold, each somewhere a prompt cannot reach:
+//
+//   · The room hands the write tools to a turn only at #4 AIRLOCK (`sends` in the module, enforced
+//     in src/modules/index.mjs). This server checks again: unless PULSE_GITHUB_WRITES=1 it does
+//     not list them and refuses to run them.
+//   · The credential is gh's own session, which this process never sees, or a token in its
+//     environment. Neither is written anywhere: not in a result, not in the outbound log.
+//   · The repository is the one the module found in the project's remotes. A tool cannot be
+//     pointed at another one.
+//
+// Environment:
+//   PULSE_GITHUB_REPO      required, owner/repo
+//   PULSE_GITHUB_ROOT      the project, to read the current branch from git
+//   PULSE_GITHUB_AUTH      'gh' or 'token'
+//   PULSE_GITHUB_GH        the gh executable, with PULSE_GITHUB_AUTH=gh
+//   PULSE_GITHUB_TOKEN     the token, with PULSE_GITHUB_AUTH=token (from MADRE's vault)
+//   PULSE_GITHUB_WRITES    '1' only in a #4 AIRLOCK turn
+//   PULSE_OUTBOUND_LOG     where each request leaves its line
+
+import { realpath } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { OutboundLog, declareDestinations } from '../outbound.mjs';
+import * as github from '../github.mjs';
+
+const SERVER_NAME = 'pulse-github';
+const SERVER_VERSION = '1.0.0';
+const SELF = fileURLToPath(import.meta.url);
+
+export const READ_TOOLS = ['github_list_prs', 'github_get_pr', 'github_ci_status', 'github_list_issues', 'github_get_issue'];
+export const WRITE_TOOLS = ['github_create_pr', 'github_comment', 'github_create_issue'];
+
+const n = { type: 'integer', minimum: 1 };
+export const TOOLS = [
+  { name: 'github_list_prs', description: 'List the open pull requests of this project\'s GitHub repository: number, title, author, branch, base, draft.', inputSchema: { type: 'object', properties: { limit: { type: 'integer', minimum: 1, maximum: 100, description: 'How many, newest first. Default 20.' } } } },
+  { name: 'github_get_pr', description: 'One pull request: title, state, branch and base, whether it can merge, additions/deletions, changed files, and the review state.', inputSchema: { type: 'object', properties: { number: { ...n, description: 'The pull request number.' } }, required: ['number'] } },
+  { name: 'github_ci_status', description: 'The checks and CI of a branch: one overall state (success, failure, pending, none), each check, and the latest workflow runs. Defaults to the branch the project is on.', inputSchema: { type: 'object', properties: { ref: { type: 'string', description: 'A branch, tag or commit. Default: the current branch.' } } } },
+  { name: 'github_list_issues', description: 'List the open issues (not pull requests): number, title, author, labels, comment count.', inputSchema: { type: 'object', properties: { limit: { type: 'integer', minimum: 1, maximum: 100, description: 'How many, newest first. Default 20.' } } } },
+  { name: 'github_get_issue', description: 'One issue: title, state, author, labels and its text.', inputSchema: { type: 'object', properties: { number: { ...n, description: 'The issue number.' } }, required: ['number'] } },
+  { name: 'github_create_pr', description: 'Open a pull request on GitHub under the human\'s name. It cannot be undone from here: before calling it, state in one line its title, from which branch and into which. The branch must already be pushed.', inputSchema: { type: 'object', properties: { title: { type: 'string' }, body: { type: 'string', description: 'The description, Markdown.' }, head: { type: 'string', description: 'The branch to merge from. Default: the current branch.' }, base: { type: 'string', description: 'The branch to merge into. Default: the repository\'s default branch.' } }, required: ['title'] } },
+  { name: 'github_comment', description: 'Post a comment on a pull request or issue under the human\'s name. It cannot be undone from here: before calling it, state in one line where it goes and what it says.', inputSchema: { type: 'object', properties: { number: { ...n, description: 'The pull request or issue number.' }, body: { type: 'string', description: 'The comment, Markdown.' } }, required: ['number', 'body'] } },
+  { name: 'github_create_issue', description: 'Open an issue on GitHub under the human\'s name. It cannot be undone from here: before calling it, state in one line its title and what it says.', inputSchema: { type: 'object', properties: { title: { type: 'string' }, body: { type: 'string', description: 'The text, Markdown.' } }, required: ['title'] } },
+];
+
+// What this process was handed, as the client wants it. The token is read here and only here.
+export function contextFrom(env = process.env) {
+  const [owner, repo] = String(env.PULSE_GITHUB_REPO ?? '').split('/');
+  const auth = env.PULSE_GITHUB_AUTH === 'gh' && env.PULSE_GITHUB_GH ? { kind: 'gh', gh: env.PULSE_GITHUB_GH }
+    : env.PULSE_GITHUB_AUTH === 'token' && env.PULSE_GITHUB_TOKEN ? { kind: 'token', token: env.PULSE_GITHUB_TOKEN }
+      : null;
+  // gh is handed an environment without the token variable it never needed.
+  const { PULSE_GITHUB_TOKEN: _drop, ...clean } = env;
+  return { repo: owner && repo ? { owner, repo, slug: `${owner}/${repo}` } : null, root: env.PULSE_GITHUB_ROOT || null, auth, writes: env.PULSE_GITHUB_WRITES === '1', env: clean };
+}
+
+let outbound = null;
+function logFor(env) {
+  if (!env.PULSE_OUTBOUND_LOG) return null;
+  // This process has its own copy of the declarations; without this, its lines would read as an
+  // address nothing here declares.
+  declareDestinations('github', github.REACHES);
+  outbound ??= new OutboundLog({ file: env.PULSE_OUTBOUND_LOG });
+  return outbound;
+}
+
+export async function callTool(name, args = {}, { env = process.env, api = github } = {}) {
+  const here = contextFrom(env);
+  if (!here.repo) throw new github.GithubError('NO_REPO', 'No repository was handed to this server.');
+  if (!here.auth) throw new github.GithubError('NO_CREDENTIAL', github.ERRORS.NO_SESSION);
+  if (WRITE_TOOLS.includes(name) && !here.writes) throw new github.GithubError('NOT_AIRLOCK', 'Writing to GitHub needs a turn in #4 AIRLOCK. Nothing was posted.');
+  const common = { repo: here.repo, auth: here.auth, log: logFor(env), env: here.env };
+  const branch = async () => (here.root ? api.currentBranch(here.root, { env: here.env }) : null);
+  switch (name) {
+    case 'github_list_prs': return { repo: here.repo.slug, pulls: await api.listPulls({ ...common, limit: args.limit }) };
+    case 'github_get_pr': return await api.getPull({ ...common, number: args.number });
+    case 'github_ci_status': {
+      const ref = String(args.ref ?? '').trim() || await branch();
+      const [ci, runs] = await Promise.all([api.ciStatus({ ...common, ref }), api.workflowRuns({ ...common, branch: ref, limit: 5 }).catch(() => [])]);
+      return { ...ci, runs };
+    }
+    case 'github_list_issues': return { repo: here.repo.slug, issues: await api.listIssues({ ...common, limit: args.limit }) };
+    case 'github_get_issue': return await api.getIssue({ ...common, number: args.number });
+    case 'github_create_pr': {
+      const head = String(args.head ?? '').trim() || await branch();
+      return await api.createPull({ ...common, title: args.title, body: args.body ?? '', head, base: String(args.base ?? '').trim() || null });
+    }
+    case 'github_comment': return await api.comment({ ...common, number: args.number, body: args.body });
+    case 'github_create_issue': return await api.createIssue({ ...common, title: args.title, body: args.body ?? '' });
+    default: throw new github.GithubError('UNKNOWN_TOOL', `Unknown tool: ${name}`);
+  }
+}
+
+export function handleRequest(message, { env = process.env, api = github } = {}) {
+  const reply = (result) => ({ jsonrpc: '2.0', id: message.id, result });
+  const fail = (code, text) => ({ jsonrpc: '2.0', id: message.id, error: { code, message: text } });
+  const writes = env.PULSE_GITHUB_WRITES === '1';
+  switch (message.method) {
+    case 'initialize':
+      return Promise.resolve(reply({ protocolVersion: message.params?.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: SERVER_NAME, version: SERVER_VERSION } }));
+    case 'notifications/initialized':
+    case 'initialized':
+      return Promise.resolve(null);
+    case 'ping':
+      return Promise.resolve(reply({}));
+    case 'tools/list':
+      // Below #4 the write tools are not merely refused: they are not here.
+      return Promise.resolve(reply({ tools: TOOLS.filter((tool) => writes || !WRITE_TOOLS.includes(tool.name)) }));
+    case 'tools/call': {
+      const { name, arguments: args = {} } = message.params ?? {};
+      if (!TOOLS.some((tool) => tool.name === name)) return Promise.resolve(fail(-32602, `Unknown tool: ${name}`));
+      const writing = WRITE_TOOLS.includes(name);
+      return callTool(name, args, { env, api })
+        .then((result) => reply({ content: [{ type: 'text', text: writing ? `Posted to GitHub: ${JSON.stringify(result)}` : JSON.stringify(result) }], isError: false }))
+        .catch((error) => {
+          const detail = error.detail ? ` GitHub said: ${error.detail}` : '';
+          const lead = writing ? 'Nothing was posted' : 'GitHub did not answer';
+          return reply({ content: [{ type: 'text', text: `${lead} (${error.code ?? 'ERROR'}): ${error.message}${detail}` }], isError: true });
+        });
+    }
+    default:
+      return Promise.resolve(message.id === undefined ? null : fail(-32601, `Method not found: ${message.method}`));
+  }
+}
+
+export function serve({ input = process.stdin, output = process.stdout, env = process.env } = {}) {
+  let buffer = '';
+  let pending = 0;
+  let ended = false;
+  const finish = () => { if (ended && pending === 0) void (outbound?.drain() ?? Promise.resolve()).finally(() => process.exit(0)); };
+  input.setEncoding('utf8');
+  input.on('data', (chunk) => {
+    buffer += chunk;
+    let index;
+    while ((index = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, index).trim();
+      buffer = buffer.slice(index + 1);
+      if (!line) continue;
+      let message;
+      try { message = JSON.parse(line); } catch { output.write(`${JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } })}\n`); continue; }
+      pending += 1;
+      void handleRequest(message, { env })
+        .then((response) => { if (response) output.write(`${JSON.stringify(response)}\n`); })
+        .finally(() => { pending -= 1; finish(); });
+    }
+  });
+  input.on('end', () => { ended = true; finish(); });
+}
+
+// Both paths resolved before they are compared: `new URL(import.meta.url).pathname` would be
+// /C:/… on Windows (WIN-004), and a path through a symlink would never match its target.
+const real = async (path) => (path ? realpath(path).catch(() => path) : null);
+if (process.argv[1] && (await real(process.argv[1])) === (await real(SELF))) {
+  if (!process.env.PULSE_GITHUB_REPO) {
+    process.stderr.write('PULSE_GITHUB_REPO is required.\n');
+    process.exit(2);
+  }
+  serve();
+}

package/src/mcp/image-server.mjs

@@ -28,7 +28,7 @@ const FAKE_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADU
 
 // Where a Gemini key can be, in the order the room should trust them: what this process was
 // given, then the file the CLI reads on every run — which is also the file MADRE itself writes
-// when a key is pasted into CONNECTIONS — and last the macOS keychain, which only exists when
+// when a key is pasted into Settings › Agents — and last the macOS keychain, which only exists when
 // the CLI's own sign-in put it there. Leaving the file out meant MADRE saved a key in a place it
 // then refused to look, and on Linux, where there is no keychain, that was the only place it
 // could have been: Image Studio could never find a key there at all.

package/src/mcp/memory-server.mjs

@@ -11,9 +11,12 @@
 //                         Gemini CLI. Without a key search is lexical only.
 
 import { readFile, readdir, stat, realpath } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { RoomMemory, formatRecall, formatMemories, MEMORY_KINDS } from '../memory.mjs';
 import { createEmbedder } from '../embeddings.mjs';
+import { loadConfig } from '../config.mjs';
+import { Privacy, privacySettings } from '../privacy.mjs';
 import { resolveGeminiKey } from './image-server.mjs';
 
 const SERVER_NAME = 'pulse-memory';
@@ -71,9 +74,13 @@ export const TOOLS = [
 
 function clamp(n, min, max, fallback) { const value = Number(n); return Number.isFinite(value) ? Math.min(max, Math.max(min, Math.trunc(value))) : fallback; }
 
-export async function openMemory({ dbFile = process.env.PULSE_MEMORY_DB, env = process.env, keyResolver = resolveGeminiKey } = {}) {
+export async function openMemory({ dbFile = process.env.PULSE_MEMORY_DB, env = process.env, keyResolver = resolveGeminiKey, stateRoot = env.PULSE_HOME ?? join(homedir(), '.pulse'), privacy = null } = {}) {
   if (!dbFile) throw new Error('PULSE_MEMORY_DB is required.');
-  const memory = await new RoomMemory(dbFile).initialize();
+  // A private term never enters a note, whoever writes it (docs/MACROVERSO.md, S-008): the guard
+  // the room attaches to its own index, built from the same config.json every room on this Mac
+  // shares, so a note an agent saves through memory_note is kept the way the archivist's are.
+  const guard = privacy ?? new Privacy({ ...privacySettings(await loadConfig(stateRoot).catch(() => ({})), env), home: homedir() });
+  const memory = await new RoomMemory(dbFile).attachPrivacy(guard).initialize();
   let embedder = null;
   if (env.PULSE_EMBED !== '0') {
     const key = env.PULSE_EMBED_FAKE === '1' ? null : await keyResolver(env).catch(() => null);
@@ -115,7 +122,8 @@ export async function callTool(name, args = {}, { memory, projectRoot = process.
       const added = memory.addMemories([{ kind, text, sources }], { agent, fromSequence: sources.length ? Math.min(...sources) : last, throughSequence: sources.length ? Math.max(...sources) : last, origin: 'noted', messageId });
       if (!added) return `Already remembered: "${text}"`;
       const [saved] = memory.notesSince(before, { agent });
-      return `Saved memory #${saved?.id ?? '?'} (${kind}) for every future turn of this room: "${text}"`;
+      // Echoed as it was kept: with a private term already replaced by the marker.
+      return `Saved memory #${saved?.id ?? '?'} (${kind}) for every future turn of this room: "${saved?.text ?? text}"`;
     }
     case 'memory_search': {
       const query = String(args.query ?? '').trim();