@jossuealcala/madre 0.2.0

package/src/adapters/process.mjs

@@ -0,0 +1,132 @@
+import { spawn } from 'node:child_process';
+
+function signalProcessGroup(child, signal) {
+  if (!child.pid) return false;
+  try {
+    // Negative pid targets the whole process group created by `detached: true`,
+    // so relaunched or wrapped CLI children die together with the launcher.
+    process.kill(-child.pid, signal);
+    return true;
+  } catch {
+    try {
+      child.kill(signal);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+export function terminateProcessTree(child, { graceMs = 2000 } = {}) {
+  signalProcessGroup(child, 'SIGTERM');
+  const escalation = setTimeout(() => signalProcessGroup(child, 'SIGKILL'), graceMs);
+  escalation.unref?.();
+  child.once('close', () => clearTimeout(escalation));
+}
+
+export function runReadonlyProcess({
+  executable,
+  args,
+  cwd,
+  env = process.env,
+  timeoutMs = 120000,
+  killGraceMs = 2000,
+  // Optional: give up when the process stays silent this long. Streaming
+  // adapters use it to tell "thinking" from "hung"; batch ones leave it off.
+  idleTimeoutMs = null,
+  // Optional: inspect accumulated stderr as it arrives; return an Error to
+  // stop the process now instead of waiting for the timeout (e.g. a CLI that
+  // retries a 503 forever).
+  watchStderr = null,
+  label,
+  parse,
+  signal,
+}) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error(`${label} was interrupted before it started: ${typeof signal.reason === 'string' ? signal.reason : 'MADRE is shutting down'}.`));
+      return;
+    }
+    const child = spawn(executable, args, {
+      cwd,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let lastActivity = Date.now();
+    let idleTimer = null;
+    const armIdle = () => {
+      if (!idleTimeoutMs) return;
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => {
+        if (settled) return;
+        if (Date.now() - lastActivity < idleTimeoutMs) { armIdle(); return; }
+        terminateProcessTree(child, { graceMs: killGraceMs });
+        const lastLine = `${stderr}\n${stdout}`.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+        const error = new Error(`${label} went silent for ${Math.round(idleTimeoutMs / 1000)}s and was stopped.${lastLine ? ` Last output: ${lastLine.slice(0, 200)}` : ''}`);
+        error.code = 'IDLE';
+        error.partialOutput = stdout;
+        error.partialStderr = stderr.slice(-2000);
+        finish(() => reject(error));
+      }, idleTimeoutMs);
+      idleTimer.unref?.();
+    };
+
+    const onAbort = () => {
+      terminateProcessTree(child, { graceMs: killGraceMs });
+      const reason = typeof signal?.reason === 'string' ? signal.reason : 'MADRE is shutting down';
+      finish(() => reject(new Error(`${label} was interrupted: ${reason}.`)));
+    };
+    const finish = (operation) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(idleTimer);
+      signal?.removeEventListener('abort', onAbort);
+      operation();
+    };
+    const timer = setTimeout(() => {
+      terminateProcessTree(child, { graceMs: killGraceMs });
+      // The last thing the agent said is usually the reason it was slow.
+      const lastLine = `${stderr}\n${stdout}`.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+      const error = new Error(`${label} did not respond before the timeout (${Math.round(timeoutMs / 1000)}s).${lastLine ? ` Last output: ${lastLine.slice(0, 200)}` : ''}`);
+      error.code = 'TIMEOUT';
+      error.partialOutput = stdout;
+      error.partialStderr = stderr.slice(-2000);
+      finish(() => reject(error));
+    }, timeoutMs);
+    signal?.addEventListener('abort', onAbort, { once: true });
+
+    // Only complete stdout lines count as activity: a CLI's stderr spinner or
+    // progress noise must not keep a silent model alive past the idle limit.
+    // Blank keep-alive lines are not activity either.
+    child.stdout.on('data', (chunk) => { stdout += chunk; if (/\S/.test(String(chunk)) && String(chunk).includes('\n')) lastActivity = Date.now(); });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+      if (!watchStderr || settled) return;
+      const verdict = watchStderr(stderr);
+      if (!verdict) return;
+      terminateProcessTree(child, { graceMs: killGraceMs });
+      verdict.code ??= 'STDERR';
+      verdict.partialOutput = stdout;
+      verdict.partialStderr = stderr.slice(-2000);
+      finish(() => reject(verdict));
+    });
+    armIdle();
+    child.on('error', (error) => finish(() => {
+      // spawn reports ENOENT for a missing cwd as well as a missing binary.
+      if (error.code === 'ENOENT') {
+        error.message = `${label} could not start: ${error.message}. Check that the project folder ${cwd} exists and that ${executable} is still installed.`;
+      }
+      reject(error);
+    }));
+    child.on('close', (code) => finish(() => {
+      const response = parse(stdout);
+      if (code === 0 && response.text) return resolve(response);
+      reject(new Error(stderr.trim() || response.error || `${label} exited with code ${code}.`));
+    }));
+  });
+}

package/src/ashcode.mjs

@@ -0,0 +1,64 @@
+// AshCode / ORDER 937 is a deliberately conservative, local text transform.
+// It is lossy, not encryption or a model tokenizer. Keep the original in the
+// event log so the human can inspect what was actually abbreviated.
+
+const SPANISH = /\b(?:el|la|los|las|un|una|unos|unas|para|proyecto|página|pagina|imagen|crear|genera|dentro)\b/gi;
+const ENGLISH = /\b(?:the|a|an|for|project|page|image|create|generate|inside|please)\b/gi;
+const PROTECTED = /"[^"\n]*"|'[^'\n]*'|@[\p{L}\p{N}_-]+|![\p{L}\p{N}_./:-]+/gu;
+const RISKY = /```|`|https?:\/\/|\n|[{}<>]|\b(?:no|nunca|sin|excepto|not|never|without|except)\b|\d|(?:^|\s)(?:\.{1,2}\/|\/|[\w.-]+\/)[\w./-]+/iu;
+
+export function ashLanguage(input) {
+  const text = String(input ?? '');
+  const es = (text.match(SPANISH) ?? []).length + (/[áéíóúñ¿¡]/i.test(text) ? 2 : 0);
+  const en = (text.match(ENGLISH) ?? []).length;
+  if (es === en || Math.max(es, en) < 2) return null;
+  return es > en ? 'es' : 'en';
+}
+
+export function compressAshCode(input) {
+  const original = String(input ?? '').trim();
+  const unchanged = (reason) => ({ text: original, original, applied: false, reason, originalChars: original.length, encodedChars: original.length, language: null });
+  if (!original) return unchanged('empty');
+  if (RISKY.test(original) || /(?:^|\s)\/[A-Za-z_.]/.test(original)) return unchanged('protected-structure');
+  const language = ashLanguage(original);
+  if (!language) return unchanged('language-uncertain');
+
+  const protectedSpans = [];
+  let text = original.replace(PROTECTED, (span) => {
+    const index = protectedSpans.push(span) - 1;
+    return `\uE000${index}\uE001`;
+  });
+
+  if (language === 'es') {
+    text = text
+      .replace(/\b(?:yo\s+)?(?:quiero|necesito|quisiera)\s+que\s+/gi, '')
+      .replace(/\bme gustaría que\s+/gi, '')
+      .replace(/\bpor favor\b[,.]?\s*/gi, '')
+      .replace(/\bdentro del?\b/gi, 'en')
+      .replace(/\b(?:el|la|los|las|un|una|unos|unas)\s+/g, '')
+      .replace(/\bhome de (?:la )?(?:página|pagina) principal\b/gi, 'home');
+  } else {
+    text = text
+      .replace(/\bI (?:would like|want|need) you to\s+/gi, '')
+      .replace(/\b(?:could|can) you\s+/gi, '')
+      .replace(/\bplease\b[,.]?\s*/gi, '')
+      .replace(/\binside of\b/gi, 'in')
+      .replace(/\b(?:the|a|an)\s+/g, '')
+      .replace(/\bhome page of (?:the )?main (?:web)?site\b/gi, 'home page');
+  }
+
+  text = text
+    .replace(/\b([\p{L}]+)(?:\s+\1)+\b/giu, '$1')
+    .replace(/\s+([,.;:!?])/g, '$1')
+    .replace(/\s{2,}/g, ' ')
+    .trim()
+    .replace(/[.。]$/, '');
+  text = text.replace(/\uE000(\d+)\uE001/g, (_, index) => protectedSpans[Number(index)]);
+  const encoded = `ASH937/${language}: ${text}`;
+  // A shorter character string is not proof of fewer model tokens. Refuse
+  // marginal rewrites because the prefix itself may erase any gain.
+  if (encoded.length > original.length - 8) return unchanged('no-safe-gain');
+  return { text: encoded, original, applied: true, reason: null, originalChars: original.length, encodedChars: encoded.length, language };
+}
+
+export const ASHCODE_BETA_WARNING = 'AshCode beta: abbreviation can change meaning or cause errors. Review the original before relying on a result; character reduction is not verified token savings.';

package/src/auth-probe.mjs

@@ -0,0 +1,145 @@
+import { execFile } from 'node:child_process';
+import { access, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const stripAnsi = (text) => String(text ?? '').replace(/\[[0-9;]*[A-Za-z]/g, '');
+
+// Pure parsers, one per CLI, so the probe can be tested without the binaries.
+
+export function parseCodexLoginStatus({ stdout = '', stderr = '', code = 0 }) {
+  const text = stripAnsi(`${stdout}\n${stderr}`);
+  if (/not logged in/i.test(text)) return { state: 'signed-out', detail: 'not logged in' };
+  if (code === 0 && /logged in/i.test(text)) {
+    const method = text.match(/logged in (?:using|with) ([^\n.]+)/i)?.[1]?.trim();
+    return { state: 'signed-in', detail: method ? `via ${method}` : 'logged in' };
+  }
+  return { state: 'unknown', detail: text.trim().split('\n')[0] || 'no status' };
+}
+
+export function parseClaudeAuthStatus({ stdout = '' }) {
+  try {
+    const status = JSON.parse(stripAnsi(stdout).trim());
+    if (status.loggedIn === true) return { state: 'signed-in', detail: status.authMethod ? `via ${status.authMethod}` : 'logged in' };
+    if (status.loggedIn === false) return { state: 'signed-out', detail: 'not logged in' };
+  } catch {
+    // fall through
+  }
+  return { state: 'unknown', detail: 'no status' };
+}
+
+export function parseOpenCodeAuthList({ stdout = '' }) {
+  const providers = stripAnsi(stdout)
+    .split('\n')
+    .map((line) => line.match(/^\s*[●○◆◇*-]\s+(.+?)\s{2,}(\S+)\s*$/) ?? line.match(/^\s*[●○◆◇*]\s+(.+?)\s+(oauth|api|apikey|token)\s*$/i))
+    .filter(Boolean)
+    .map((match) => ({ name: match[1].trim(), type: match[2].trim() }));
+  if (providers.length) {
+    return { state: 'signed-in', detail: providers.map((provider) => `${provider.name} (${provider.type})`).join(', '), providers };
+  }
+  return { state: 'signed-out', detail: 'no providers configured', providers: [] };
+}
+
+export function geminiAuthState({ settings, hasOauth, hasApiKey }) {
+  const type = settings?.security?.auth?.selectedType;
+  if (type === 'gemini-api-key') return hasApiKey ? { state: 'signed-in', detail: 'via API key' } : { state: 'signed-out', detail: 'API key selected but not found' };
+  if (type === 'oauth-personal' || type === 'oauth-enterprise') return hasOauth ? { state: 'signed-in', detail: 'via Google account' } : { state: 'signed-out', detail: 'Google login selected but no token' };
+  if (type === 'vertex-ai') return { state: 'signed-in', detail: 'via Vertex AI' };
+  if (hasApiKey || hasOauth) return { state: 'unknown', detail: 'credentials present, auth type not selected' };
+  return { state: 'signed-out', detail: 'never signed in' };
+}
+
+async function run(path, args, timeout = 6000) {
+  try {
+    const { stdout, stderr } = await execFileAsync(path, args, { timeout, env: { ...process.env, NO_COLOR: '1' } });
+    return { stdout, stderr, code: 0 };
+  } catch (error) {
+    return { stdout: error.stdout ?? '', stderr: error.stderr ?? error.message, code: error.code ?? 1 };
+  }
+}
+
+const exists = (path) => access(path).then(() => true, () => false);
+
+async function geminiHasKeychainKey() {
+  if (process.platform !== 'darwin') return false;
+  const result = await run('/usr/bin/security', ['find-generic-password', '-s', 'gemini-cli-api-key'], 3000);
+  return result.code === 0;
+}
+
+export async function probeGemini({ env = process.env } = {}) {
+  const home = env.GEMINI_CLI_HOME ?? homedir();
+  const dir = join(home, '.gemini');
+  let settings = null;
+  try {
+    settings = JSON.parse(await readFile(join(dir, 'settings.json'), 'utf8'));
+  } catch {
+    settings = null;
+  }
+  const hasOauth = await exists(join(dir, 'oauth_creds.json'));
+  const hasApiKey = Boolean(env.GEMINI_API_KEY || env.GOOGLE_API_KEY) || await geminiHasKeychainKey();
+  return geminiAuthState({ settings, hasOauth, hasApiKey });
+}
+
+// What each CLI needs from the user. Commands are run in the user's terminal
+// by the setup wizard; install hints are only printed.
+export const AGENT_SETUP = {
+  codex: {
+    install: ['npm install -g @openai/codex', 'or install the ChatGPT desktop app, which bundles codex'],
+    login: ['login'],
+    loginNote: 'Opens your browser to sign in with ChatGPT.',
+    browser: true,
+  },
+  claude: {
+    install: ['npm install -g @anthropic-ai/claude-code', 'or: brew install --cask claude-code'],
+    login: ['auth', 'login'],
+    loginNote: 'Opens your browser to sign in with your Claude account.',
+    browser: true,
+  },
+  gemini: {
+    install: ['npm install -g @google/gemini-cli'],
+    login: [],
+    loginNote: 'Gemini signs in from its own prompt: run `gemini`, type /auth, pick "Use Gemini API key" (get one at aistudio.google.com/app/apikey) or Google login.',
+    interactive: true,
+  },
+  opencode: {
+    install: ['brew install opencode', 'or: npm install -g opencode-ai'],
+    login: ['auth', 'login'],
+    loginNote: 'Pick a provider and paste its key or complete its OAuth flow.',
+  },
+};
+
+// How the room can (re)connect an agent. Codex and Claude sign in with a
+// browser flow their own CLI drives, so the server can run them and stream the
+// URL; Gemini and OpenCode need their interactive prompt, so the user gets the
+// exact command instead.
+export function loginPlanFor(agent) {
+  const setup = AGENT_SETUP[agent.id];
+  if (!setup) return null;
+  const headless = Boolean(setup.browser) && setup.login.length > 0;
+  return {
+    headless,
+    command: agent.path ?? agent.id,
+    args: headless ? setup.login : [],
+    display: headless ? `${agent.id} ${setup.login.join(' ')}` : agent.id === 'gemini' ? 'gemini   # then type /auth' : `${agent.id} ${setup.login.join(' ')}`,
+    note: setup.loginNote,
+    install: setup.install,
+  };
+}
+
+export async function probeAgentAuth(agent) {
+  if (!agent.detected || !agent.path) return { state: 'not-installed', detail: 'not found on this computer' };
+  switch (agent.id) {
+    case 'codex': return parseCodexLoginStatus(await run(agent.path, ['login', 'status']));
+    case 'claude': return parseClaudeAuthStatus(await run(agent.path, ['auth', 'status', '--json']));
+    case 'opencode': return parseOpenCodeAuthList(await run(agent.path, ['auth', 'list']));
+    case 'gemini': return probeGemini();
+    default: return { state: 'unknown', detail: 'no probe for this agent' };
+  }
+}
+
+export async function probeAll(agents) {
+  const results = await Promise.all(agents.map((agent) => probeAgentAuth(agent)));
+  return Object.fromEntries(agents.map((agent, index) => [agent.id, results[index]]));
+}

package/src/capabilities.mjs

@@ -0,0 +1,126 @@
+// What each CLI can do from MADRE, verified against the installed versions on
+// 2026-09-16 (Codex 0.153, Claude Code 2.1, Gemini CLI 0.60, OpenCode 1.18).
+// The room shows this so a human knows whom to ask for what, and an
+// orchestrator can route steps to the agent that actually has the ability.
+//
+//   read       inspect the project (always on: consultation mode)
+//   imageIn    accept an image the human attaches
+//   write      create files, only inside a scoped output directory, only when
+//              the human grants a creation lease for the turn (phase 2)
+//   imageGen   generate images (Codex: image_generation feature via ChatGPT)
+//   web        fetch or search the web (denied by default in consultation mode)
+
+export const CAPABILITIES = {
+  codex: {
+    read: true,
+    imageIn: { how: '-i <file>', note: 'Images attach to the prompt directly.' },
+    write: { how: '-C <outdir> --sandbox workspace-write', note: 'Reads the whole project, writes only inside the lease directory.' },
+    imageGen: { how: 'features.image_generation (stable, enabled)', note: 'Generated with the ChatGPT account; saved into the lease directory.' },
+    web: { how: '--search (live web_search tool)', note: 'Off until enabled in CONNECTIONS.' },
+  },
+  claude: {
+    read: true,
+    imageIn: { how: 'Read tool on the attachment path', note: 'The attachments folder is added with --add-dir.' },
+    write: { how: '--tools Write,Edit + permission rules', note: 'Write/Edit allowed only under the lease directory.' },
+    imageGen: false,
+    web: { how: '--tools WebFetch,WebSearch', note: 'Off until enabled in CONNECTIONS.' },
+  },
+  gemini: {
+    read: true,
+    imageIn: { how: 'read_file on the attachment path', note: 'The attachments folder is added with --include-directories.' },
+    write: { how: 'policy: allow write_file/edit with argsPattern', note: 'Paths outside the lease directory stay denied.' },
+    imageGen: false,
+    web: { how: 'policy: allow google_web_search, web_fetch', note: 'Off until enabled in CONNECTIONS.' },
+  },
+  opencode: {
+    read: true,
+    imageIn: { how: '-f <file>', note: 'Files attach to the message.' },
+    write: { how: 'permission.edit patterns', note: 'Edit allowed only under the lease directory.' },
+    imageGen: false,
+    web: { how: 'permission.webfetch / websearch = allow', note: 'Off until enabled in CONNECTIONS.' },
+  },
+};
+
+// MADRE modules can add abilities a CLI lacks. Image Studio (MADRE's own MCP
+// image server on the Gemini API) gives Gemini CLI, Claude Code and OpenCode
+// image generation; Codex keeps its native one.
+let imageModule = { enabled: false };
+export function setImageModule(state) {
+  imageModule = { enabled: Boolean(state?.enabled), model: state?.model ?? null };
+}
+export const imageModuleState = () => ({ ...imageModule });
+
+export const capabilityOf = (agentId) => {
+  const base = CAPABILITIES[agentId] ?? { read: true, imageIn: false, write: false, imageGen: false, web: false };
+  if (!base.imageGen && imageModule.enabled && ['gemini', 'claude', 'opencode'].includes(agentId)) {
+    return { ...base, imageGen: { how: 'MADRE Image Studio (MCP tool generate_image, Gemini API)', note: `Attached only inside a creation lease with the image scope on${imageModule.model ? ` · model ${imageModule.model}` : ''}.`, module: 'image-studio' } };
+  }
+  return base;
+};
+
+export function capabilitySummary(agentId) {
+  const caps = capabilityOf(agentId);
+  return {
+    read: Boolean(caps.read),
+    imageIn: Boolean(caps.imageIn),
+    write: Boolean(caps.write),
+    imageGen: Boolean(caps.imageGen),
+    web: Boolean(caps.web),
+    detail: Object.fromEntries(Object.entries(caps).filter(([, value]) => value && typeof value === 'object').map(([key, value]) => [key, value])),
+  };
+}
+
+// Agents that have a capability, for routing hints in the delegation help.
+export function agentsWith(capability, agentIds) {
+  return agentIds.filter((id) => Boolean(capabilityOf(id)[capability]));
+}
+
+// Permission modes, chosen per message in the composer and capped per agent
+// in CONNECTIONS. The human's mode is the ceiling of any plan it starts.
+//   #0 GHOST     off the record: nothing enters the log or anyone's context
+//   #1 EXCHANGE  read the project, coordinate with the others (default)
+//   #2 CREATE    create files and images inside the turn's .pulse/out/ lease
+//   #3 CONTROL   read, create and modify the project itself (phase C)
+export const MODES = {
+  0: { key: 'ghost', label: 'GHOST', hint: 'off the record · nothing is saved or remembered' },
+  1: { key: 'exchange', label: 'EXCHANGE', hint: 'read the project and coordinate · default' },
+  2: { key: 'create', label: 'CREATE', hint: 'create files and images inside .pulse/out/' },
+  3: { key: 'control', label: 'CONTROL', hint: 'modify the project itself · only this agent · needs the override' },
+};
+export const MODE_MAX = 3;
+export const normalizeMode = (value, fallback = 1) => {
+  const mode = Number(value);
+  return Number.isInteger(mode) && mode >= 0 && mode <= MODE_MAX ? mode : fallback;
+};
+
+// Scopes are the capabilities the human has switched on for CREATE. A scope
+// can only be enabled where the CLI has the capability; by default file
+// creation and image generation are on wherever possible, web stays off.
+export const SCOPES = ['write', 'imageGen', 'web'];
+export const SCOPE_LABELS = { write: 'create files', imageGen: 'generate images', web: 'web access' };
+
+export function resolveScopes(agentId, configured = {}) {
+  const caps = capabilityOf(agentId);
+  const scopes = {};
+  for (const scope of SCOPES) {
+    const capable = Boolean(caps[scope]);
+    const wanted = configured[scope] ?? (scope !== 'web');
+    scopes[scope] = { capable, enabled: capable && wanted, wired: true };
+  }
+  // A standing lease: every turn of this agent may create files inside
+  // .pulse/out/ without the human arming CREATE each time. Opt-in per agent.
+  scopes.write.always = Boolean(configured.alwaysCreate) && scopes.write.enabled;
+  // The ceiling: how far the composer may take this agent. Writing needs the
+  // CLI to be able to write; CONTROL is capped at 2 until phase C wires it.
+  const wanted = normalizeMode(configured.maxMode, scopes.write.enabled ? 2 : 1);
+  scopes.maxMode = Math.min(wanted, scopes.write.capable ? 3 : 1);
+  scopes.defaultMode = scopes.write.always && scopes.maxMode >= 2 ? 2 : 1;
+  return scopes;
+}
+
+// One line per agent for the orchestrator: who can do what right now.
+export function abilityLine(agentId, scopes) {
+  const on = SCOPES.filter((scope) => scopes[scope]?.enabled && scopes[scope]?.wired).map((scope) => SCOPE_LABELS[scope]);
+  const cannot = SCOPES.filter((scope) => !scopes[scope]?.capable).map((scope) => SCOPE_LABELS[scope]);
+  return `@${agentId}: can ${on.length ? on.join(', ') : 'only read'}${cannot.length ? `; cannot ${cannot.join(', ')}` : ''}`;
+}

package/src/checkpoint.mjs

@@ -0,0 +1,106 @@
+import { execFile } from 'node:child_process';
+import { access, mkdtemp, rm, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+// CONTROL turns run between two photographs of the project. The photograph
+// is a real git commit, kept under MADRE's own ref namespace so the user's
+// branch, index and stash never notice; it is taken with a throwaway index
+// so it includes untracked files (but never ignored ones). UNDO restores the
+// working tree to that photograph and removes what appeared since.
+
+export const CHECKPOINT_REF = 'refs/madre/checkpoints';
+
+// Paths no agent touches even in CONTROL. Enforced after the turn: whatever
+// changed here is restored from the checkpoint and reported.
+export const FORBIDDEN = [
+  /^\.git(\/|$)/,
+  /^\.pulse(\/|$)/,
+  /(^|\/)\.env(\.|$)/,
+  /(^|\/)\.madre(\/|$)/,
+  /(^|\/)\.claude\/settings\.local\.json$/,
+];
+export const isForbidden = (path) => FORBIDDEN.some((pattern) => pattern.test(path));
+
+async function git(root, args, { env = {} } = {}) {
+  const { stdout } = await execFileAsync('git', ['-c', 'core.quotepath=off', ...args], { cwd: root, env: { ...process.env, GIT_PAGER: 'cat', ...env }, maxBuffer: 16 * 1024 * 1024 });
+  return stdout;
+}
+
+export async function isGitRepo(root) {
+  return access(join(root, '.git')).then(() => true, () => false);
+}
+
+// A tree object of the working tree as it is right now: tracked and untracked
+// files, ignored ones left out. Built in a temporary index.
+export async function worktreeTree(root) {
+  const dir = await mkdtemp(join(tmpdir(), 'madre-index-'));
+  const index = join(dir, 'index');
+  try {
+    const env = { GIT_INDEX_FILE: index };
+    await git(root, ['read-tree', '--empty'], { env });
+    await git(root, ['add', '-A', '--', '.'], { env });
+    return (await git(root, ['write-tree'], { env })).trim();
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+export async function createCheckpoint(root, { id, label = 'MADRE checkpoint' } = {}) {
+  const tree = await worktreeTree(root);
+  const head = (await git(root, ['rev-parse', '--verify', '-q', 'HEAD']).catch(() => '')).trim() || null;
+  const commit = (await git(root, ['commit-tree', tree, ...(head ? ['-p', head] : []), '-m', `${label} ${id}`], { env: { GIT_AUTHOR_NAME: 'MADRE', GIT_AUTHOR_EMAIL: 'madre@localhost', GIT_COMMITTER_NAME: 'MADRE', GIT_COMMITTER_EMAIL: 'madre@localhost' } })).trim();
+  await git(root, ['update-ref', `${CHECKPOINT_REF}/${id}`, commit]);
+  return { id, commit, tree, head, createdAt: new Date().toISOString() };
+}
+
+// What changed since the checkpoint: name-status per file and git's --stat.
+export async function diffCheckpoint(root, checkpoint) {
+  const after = await worktreeTree(root);
+  if (after === checkpoint.tree) return { afterTree: after, files: [], stat: '', forbidden: [] };
+  const nameStatus = await git(root, ['diff', '--name-status', '-M', checkpoint.tree, after]);
+  const files = nameStatus.split('\n').filter(Boolean).map((line) => {
+    const [status, ...rest] = line.split('\t');
+    const path = rest.at(-1);
+    return { status: status[0], path, from: status[0] === 'R' ? rest[0] : undefined };
+  });
+  const stat = (await git(root, ['diff', '--stat=100', checkpoint.tree, after])).trim();
+  return { afterTree: after, files, stat, forbidden: files.filter((file) => isForbidden(file.path)).map((file) => file.path) };
+}
+
+// Put the working tree back to the checkpoint: files added since are removed,
+// everything else is restored from the checkpoint commit. `paths` limits the
+// restore to those files (used for forbidden zones right after a turn).
+export async function restoreCheckpoint(root, checkpoint, { paths = null } = {}) {
+  const { files } = await diffCheckpoint(root, checkpoint);
+  const chosen = paths ? files.filter((file) => paths.includes(file.path)) : files;
+  const removed = [];
+  const restored = [];
+  const canonicalRoot = resolve(root);
+  for (const file of chosen) {
+    const absolute = resolve(root, file.path);
+    if (!absolute.startsWith(canonicalRoot + sep)) continue;
+    if (file.status === 'A') {
+      await unlink(absolute).catch(() => {});
+      removed.push(file.path);
+    } else {
+      if (file.status === 'R' && file.from) {
+        await unlink(absolute).catch(() => {});
+        await git(root, ['restore', '--source', checkpoint.commit, '--worktree', '--', file.from]);
+        restored.push(file.from);
+        removed.push(file.path);
+        continue;
+      }
+      await git(root, ['restore', '--source', checkpoint.commit, '--worktree', '--', file.path]);
+      restored.push(file.path);
+    }
+  }
+  return { removed, restored };
+}
+
+export async function dropCheckpoint(root, checkpoint) {
+  await git(root, ['update-ref', '-d', `${CHECKPOINT_REF}/${checkpoint.id}`]).catch(() => {});
+}

package/src/cli-args.mjs

@@ -0,0 +1,38 @@
+// 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
+// did not.
+
+export function parseArgs(argv) {
+  const args = [...argv];
+  const helpFlags = new Set(['help', '--help', '-h']);
+  const command = helpFlags.has(args[0])
+    ? 'help'
+    : args[0]?.startsWith('-') ? 'start' : (args.shift() ?? 'start');
+
+  const options = {};
+  const flags = new Set();
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg.startsWith('--')) continue;
+    const equals = arg.indexOf('=');
+    if (equals > 0) {
+      options[arg.slice(2, equals)] = arg.slice(equals + 1);
+      continue;
+    }
+    const name = arg.slice(2);
+    const next = args[index + 1];
+    if (next !== undefined && !next.startsWith('-')) {
+      options[name] = next;
+      index += 1;
+    } else {
+      flags.add(name);
+    }
+  }
+  return {
+    command,
+    option: (name, fallback) => options[name] ?? fallback,
+    has: (name) => flags.has(name) || name in options,
+    explicit: (name) => name in options,
+  };
+}