@jossuealcala/madre 0.7.2 → 1.0.0

package/src/chats.mjs

@@ -15,9 +15,10 @@
 //
 // Nothing here starts a room or reads a ledger. It keeps the list.
 
-import { readFile, writeFile, mkdir, rm, readdir, open, stat } from 'node:fs/promises';
+import { readFile, mkdir, rm, readdir, open, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { oneAtATime, writeWhole } from './json-file.mjs';
 
 export const MAIN_CHAT = 'main';
 export const CHAT_TITLE_MAX = 80;
@@ -38,11 +39,14 @@ async function readIndex(roomDir) {
   return null;
 }
 
+// Written whole, one change at a time (src/json-file.mjs): a rename, a new conversation and a
+// message arriving read and wrote the list at once, and the last one wrote over the others
+// (LOG-11 of the 1.0 review); and a write cut halfway left a list nobody could read.
 async function writeIndex(roomDir, index) {
-  await mkdir(roomDir, { recursive: true }).catch(() => {});
-  await writeFile(join(roomDir, FILE), JSON.stringify(index, null, 2));
+  await writeWhole(join(roomDir, FILE), JSON.stringify(index, null, 2));
   return index;
 }
+const indexTurn = (roomDir, work) => oneAtATime(join(roomDir, FILE), work);
 
 // The list, with the first conversation always in it. A room that predates conversations reads
 // as one conversation, which is what it was.
@@ -55,14 +59,22 @@ export async function chatIndex(roomDir) {
   return index;
 }
 
+// A conversation named or previewed by a message BISHOP's channel brought, before the room learned
+// to leave out the header its agent reads: shown without it (docs/MACROVERSO.md, fase 4c).
+const withoutRelayHeader = (line) => {
+  if (typeof line !== 'string' || !line.startsWith('BISHOP › ')) return line;
+  const task = line.replace(/^BISHOP › .*?(?:other rooms(?: in this turn)?\.|ends with the answer\.)\s*/, '');
+  // Cut short inside the header (titles and previews are kept short): only the sender is left.
+  return task && !task.startsWith('BISHOP › ') ? task : 'Coordinator';
+};
 const shape = (id, entry, active) => ({
   id,
-  title: entry.title || (id === MAIN_CHAT ? 'First conversation' : 'Untitled'),
+  title: withoutRelayHeader(entry.title) || (id === MAIN_CHAT ? 'First conversation' : 'Untitled'),
   named: Boolean(entry.title),
   createdAt: entry.createdAt ?? null,
   updatedAt: entry.updatedAt ?? entry.createdAt ?? null,
   messages: Number(entry.messages ?? 0),
-  preview: entry.preview ?? null,
+  preview: withoutRelayHeader(entry.preview) ?? null,
   active: id === active,
 });
 
@@ -75,17 +87,24 @@ export async function listChats(roomDir) {
   return { active: index.active, chats };
 }
 
-export async function createChat(roomDir, { title = null, now = new Date().toISOString() } = {}) {
+export function createChat(roomDir, ...rest) {
+  return indexTurn(roomDir, () => createChatNow(roomDir, ...rest));
+}
+async function createChatNow(roomDir, { title = null, now = new Date().toISOString(), activate = true } = {}) {
   const index = await chatIndex(roomDir);
   const id = randomUUID().replace(/-/g, '').slice(0, 16);
   index.chats[id] = { title: title ? String(title).slice(0, CHAT_TITLE_MAX) : null, createdAt: now, updatedAt: now, messages: 0, preview: null };
-  index.active = id;
+  // A conversation started from a phone is the phone's: the room keeps the one it had open.
+  if (activate) index.active = id;
   await mkdir(join(roomDir, 'chats', id), { recursive: true });
   await writeIndex(roomDir, index);
   return shape(id, index.chats[id], index.active);
 }
 
-export async function openChat(roomDir, id) {
+export function openChat(roomDir, ...rest) {
+  return indexTurn(roomDir, () => openChatNow(roomDir, ...rest));
+}
+async function openChatNow(roomDir, id) {
   const index = await chatIndex(roomDir);
   if (!index.chats[id]) return null;
   index.active = id;
@@ -93,7 +112,10 @@ export async function openChat(roomDir, id) {
   return shape(id, index.chats[id], index.active);
 }
 
-export async function renameChat(roomDir, id, title) {
+export function renameChat(roomDir, ...rest) {
+  return indexTurn(roomDir, () => renameChatNow(roomDir, ...rest));
+}
+async function renameChatNow(roomDir, id, title) {
   const index = await chatIndex(roomDir);
   if (!index.chats[id]) return null;
   const named = String(title ?? '').trim().slice(0, CHAT_TITLE_MAX);
@@ -105,7 +127,10 @@ export async function renameChat(roomDir, id, title) {
 // Deleting a conversation takes its transcript and nothing else: whatever the archivist distilled
 // from it is the project's memory, not the conversation's, and it stays. The last conversation
 // cannot be deleted — a room always has somewhere to talk.
-export async function deleteChat(roomDir, id) {
+export function deleteChat(roomDir, ...rest) {
+  return indexTurn(roomDir, () => deleteChatNow(roomDir, ...rest));
+}
+async function deleteChatNow(roomDir, id) {
   const index = await chatIndex(roomDir);
   if (!index.chats[id]) return null;
   if (Object.keys(index.chats).length < 2) return { error: 'A room always has one conversation. Start another before deleting this one.' };
@@ -120,7 +145,10 @@ export async function deleteChat(roomDir, id) {
 // What the list shows about a conversation, kept as it happens rather than by reading every
 // ledger to draw a sidebar. A conversation with no name of its own takes the first thing the
 // human said in it, which is what they will look for.
-export async function touchChat(roomDir, id, { text = null, now = new Date().toISOString(), counts = true } = {}) {
+export function touchChat(roomDir, ...rest) {
+  return indexTurn(roomDir, () => touchChatNow(roomDir, ...rest));
+}
+async function touchChatNow(roomDir, id, { text = null, now = new Date().toISOString(), counts = true } = {}) {
   const index = await chatIndex(roomDir);
   const entry = index.chats[id];
   if (!entry) return null;
@@ -139,7 +167,10 @@ export async function touchChat(roomDir, id, { text = null, now = new Date().toI
 
 // Conversations whose folder is on disk but which no index knows about: a room copied by hand, or
 // an index lost. They are listed rather than ignored, because a transcript is not disposable.
-export async function adoptStrays(roomDir) {
+export function adoptStrays(roomDir, ...rest) {
+  return indexTurn(roomDir, () => adoptStraysNow(roomDir, ...rest));
+}
+async function adoptStraysNow(roomDir) {
   let folders = [];
   try { folders = await readdir(join(roomDir, 'chats')); } catch { return { adopted: [] }; }
   const index = await chatIndex(roomDir);
@@ -163,17 +194,23 @@ export async function lastSequenceOf(file, { window = 65536 } = {}) {
     const size = (await stat(file)).size;
     if (!size) return 0;
     handle = await open(file, 'r');
-    const length = Math.min(window, size);
-    const buffer = Buffer.alloc(length);
-    await handle.read(buffer, 0, length, size - length);
-    const lines = buffer.toString('utf8').split('\n').filter(Boolean);
-    for (let i = lines.length - 1; i >= 0; i -= 1) {
-      try {
-        const event = JSON.parse(lines[i]);
-        if (Number.isInteger(event?.sequence)) return event.sequence;
-      } catch { /* a half line at the window's edge, or a torn write: keep looking back */ }
+    // The window doubles until it finds a whole event or holds the whole file (LOG-09 of the 1.0
+    // review): one window only, a last line longer than it — a long answer — read as 0, and the
+    // conversation opened on numbers another one had already used, which the archive then dropped.
+    for (let length = Math.min(window, size); ; length = Math.min(length * 2, size)) {
+      const buffer = Buffer.alloc(length);
+      await handle.read(buffer, 0, length, size - length);
+      const lines = buffer.toString('utf8').split('\n').filter(Boolean);
+      for (let i = lines.length - 1; i >= 0; i -= 1) {
+        // The first line of a window that does not start the file may be cut: it is read again whole.
+        if (i === 0 && length < size) break;
+        try {
+          const event = JSON.parse(lines[i]);
+          if (Number.isInteger(event?.sequence)) return event.sequence;
+        } catch { /* a torn write: keep looking back */ }
+      }
+      if (length >= size) return 0;
     }
-    return 0;
   } catch {
     return 0;
   } finally {

package/src/checkpoint.mjs

@@ -1,7 +1,7 @@
 import { execFile } from 'node:child_process';
-import { access, mkdir, mkdtemp, readdir, rm, unlink } from 'node:fs/promises';
+import { access, mkdir, mkdtemp, readFile, readdir, rm, rmdir, stat, unlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, resolve, sep } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
 import { createHash } from 'node:crypto';
 import { promisify } from 'node:util';
 
@@ -17,12 +17,14 @@ 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.
+// Read without regard to case (2026-10-12, SRV-05): on a Mac the disk does not tell `.ENV` from
+// `.env`, so `.ENV` was the same file under a name no rule caught.
 export const FORBIDDEN = [
-  /^\.git(\/|$)/,
-  /^\.pulse(\/|$)/,
-  /(^|\/)\.env(\.|$)/,
-  /(^|\/)\.madre(\/|$)/,
-  /(^|\/)\.claude\/settings\.local\.json$/,
+  /^\.git(\/|$)/i,
+  /^\.pulse(\/|$)/i,
+  /(^|\/)\.env(\.|$)/i,
+  /(^|\/)\.madre(\/|$)/i,
+  /(^|\/)\.claude\/settings\.local\.json$/i,
 ];
 export const isForbidden = (path) => FORBIDDEN.some((pattern) => pattern.test(path));
 
@@ -45,36 +47,94 @@ async function shadowFor(root) {
   }
   return shadows.get(canonical);
 }
-async function gitArgs(root) {
-  if (await isGitRepo(root)) return [];
-  return ['--git-dir', await shadowFor(root), '--work-tree', root];
+// Which repository a photograph lives in: null for the project's own, or the shadow's path. A
+// checkpoint keeps the answer it was taken with. Asked again after the turn, the answer changes the
+// moment an agent runs `git init` in a project that had none: the diff then looked for the
+// shadow's commits in the brand-new repository, git failed, and a turn that had done exactly what
+// it was asked was reported as failed, with no list of changes and no UNDO.
+async function repositoryFor(root) {
+  return (await isGitRepo(root)) ? null : shadowFor(root);
+}
+async function gitArgs(root, via) {
+  const dir = via === undefined ? await repositoryFor(root) : via;
+  return dir ? ['--git-dir', dir, '--work-tree', root] : [];
 }
 
-async function git(root, args, { env = {} } = {}) {
-  const { stdout } = await execFileAsync('git', ['-c', 'core.quotepath=off', ...(await gitArgs(root)), ...args], { cwd: root, env: { ...process.env, GIT_PAGER: 'cat', ...env }, maxBuffer: 16 * 1024 * 1024 });
+// How MADRE runs git in a project (2026-10-12, CKP-01 of the 1.0 review): never running anything the
+// repository's own settings name. `.git` stays writable while an agent works — the CLIs need it —
+// and git status never shows what changes inside it, so a `core.fsmonitor` written into
+// `.git/config` during a #3 turn ran, with MADRE's rights and outside the agent's sandbox, the
+// next time MADRE photographed the project. Hooks, external diffs and text conversions are named
+// the same way; none of them is needed to take or compare a photograph.
+const SAFE = ['-c', 'core.quotepath=off', '-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', '-c', 'diff.external='];
+async function git(root, args, { env = {}, via } = {}) {
+  const { stdout } = await execFileAsync('git', [...SAFE, ...(await gitArgs(root, via)), ...args], { cwd: root, env: { ...process.env, GIT_PAGER: 'cat', ...env }, maxBuffer: 16 * 1024 * 1024 });
   return stdout;
 }
 
+// What a repository runs on its own: its settings, its hooks and its attributes (which name the
+// filters the settings define). Photographed before a turn that may write, put back after it before
+// git runs again — a write into `.git` is a write into a forbidden zone like any other.
+const CONTROLS = ['config', 'info/attributes'];
+async function gitDirOf(root, via) {
+  if (via) return via;
+  const dotgit = join(root, '.git');
+  const info = await stat(dotgit).catch(() => null);
+  if (info?.isDirectory()) return dotgit;
+  if (info?.isFile()) {
+    const pointer = (await readFile(dotgit, 'utf8').catch(() => '')).match(/^gitdir:\s*(.+)$/m)?.[1]?.trim();
+    return pointer ? resolve(root, pointer) : null;
+  }
+  return null;
+}
+async function photographControls(root, via, label) {
+  const gitDir = await gitDirOf(root, via);
+  if (!gitDir) return null;
+  const files = {};
+  for (const name of CONTROLS) files[name] = await readFile(join(gitDir, name)).catch(() => null);
+  for (const name of await readdir(join(gitDir, 'hooks')).catch(() => [])) files[`hooks/${name}`] = await readFile(join(gitDir, 'hooks', name)).catch(() => null);
+  return { gitDir, label, files };
+}
+// Puts back what changed and answers what it put back, as the project would name it.
+async function restoreControls(shot) {
+  if (!shot) return [];
+  const back = [];
+  const now = {};
+  for (const name of CONTROLS) now[name] = await readFile(join(shot.gitDir, name)).catch(() => null);
+  for (const name of await readdir(join(shot.gitDir, 'hooks')).catch(() => [])) now[`hooks/${name}`] = await readFile(join(shot.gitDir, 'hooks', name)).catch(() => null);
+  for (const name of new Set([...Object.keys(shot.files), ...Object.keys(now)])) {
+    const was = shot.files[name] ?? null;
+    const is = now[name] ?? null;
+    if (was === null && is === null) continue;
+    if (was && is && was.equals(is)) continue;
+    const path = join(shot.gitDir, name);
+    if (was === null) await rm(path, { force: true, recursive: true }).catch(() => {});
+    else { await mkdir(dirname(path), { recursive: true }); await writeFile(path, was); }
+    back.push(`${shot.label}${name}`);
+  }
+  return back;
+}
+
 // 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, { exclude = [] } = {}) {
+export async function worktreeTree(root, { exclude = [], via } = {}) {
   const dir = await mkdtemp(join(tmpdir(), 'madre-index-'));
   const index = join(dir, 'index');
   try {
     const env = { GIT_INDEX_FILE: index };
-    const extra = await gitArgs(root);
-    await git(root, ['read-tree', '--empty'], { env });
+    const extra = await gitArgs(root, via);
+    await git(root, ['read-tree', '--empty'], { env, via });
     // Every file of the working tree that git would not ignore, listed against the empty
     // index. Nested repositories come back as `dir/` entries and are left out: they are
     // photographed on their own, and `git add` would refuse one without commits anyway.
-    const listed = await git(root, ['ls-files', '-z', '--others', '--exclude-standard', '--', '.'], { env });
+    const listed = await git(root, ['ls-files', '-z', '--others', '--exclude-standard', '--', '.'], { env, via });
     const skip = new Set(exclude.map((path) => path.replace(/\/$/, '')));
     // Lock folders (MADRE's own `*.lock/`) come and go between the listing and the indexing.
     const files = listed.split('\0').filter((path) => path && !path.endsWith('/') && !/(^|\/)[^/]+\.lock\//.test(path) && ![...skip].some((dir) => path === dir || path.startsWith(`${dir}/`)));
     if (files.length) {
       // --remove: a file that vanished since the listing is dropped instead of aborting the photograph.
       const index_ = (list) => new Promise((resolvePromise, reject) => {
-        const child = execFile('git', ['-c', 'core.quotepath=off', ...extra, 'update-index', '--add', '--remove', '-z', '--stdin'], { cwd: root, env: { ...process.env, GIT_PAGER: 'cat', ...env }, maxBuffer: 64 * 1024 * 1024 }, (error) => (error ? reject(error) : resolvePromise()));
+        const child = execFile('git', [...SAFE, ...extra, 'update-index', '--add', '--remove', '-z', '--stdin'], { cwd: root, env: { ...process.env, GIT_PAGER: 'cat', ...env }, maxBuffer: 64 * 1024 * 1024 }, (error) => (error ? reject(error) : resolvePromise()));
         child.stdin.end(list.join('\0') + '\0');
       });
       try { await index_(files); } catch {
@@ -84,7 +144,7 @@ export async function worktreeTree(root, { exclude = [] } = {}) {
         if (alive.length) await index_(alive);
       }
     }
-    return (await git(root, ['write-tree'], { env })).trim();
+    return (await git(root, ['write-tree'], { env, via })).trim();
   } finally {
     await rm(dir, { recursive: true, force: true, maxRetries: 6, retryDelay: 60 });
   }
@@ -112,11 +172,12 @@ export async function nestedRepos(root, { maxDepth = 3 } = {}) {
 }
 
 async function checkpointOne(root, { id, label, exclude = [] }) {
-  const tree = await worktreeTree(root, { exclude });
-  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 { commit, tree, head };
+  const via = await repositoryFor(root);
+  const tree = await worktreeTree(root, { exclude, via });
+  const head = (await git(root, ['rev-parse', '--verify', '-q', 'HEAD'], { via }).catch(() => '')).trim() || null;
+  const commit = (await git(root, ['commit-tree', tree, ...(head ? ['-p', head] : []), '-m', `${label} ${id}`], { via, 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], { via });
+  return { commit, tree, head, via };
 }
 
 export async function createCheckpoint(root, { id, label = 'MADRE checkpoint' } = {}) {
@@ -126,20 +187,43 @@ export async function createCheckpoint(root, { id, label = 'MADRE checkpoint' }
   for (const dir of dirs) {
     try { nested.push({ dir, ...(await checkpointOne(join(root, dir), { id, label })) }); } catch { /* a broken nested repo is left alone */ }
   }
-  return { id, ...outer, nested, exclude: dirs, createdAt: new Date().toISOString() };
+  const controls = [await photographControls(root, outer.via, outer.via ? 'MADRE · ' : '.git/')];
+  for (const part of nested) controls.push(await photographControls(join(root, part.dir), part.via, `${part.dir}/.git/`));
+  return { id, ...outer, nested, exclude: dirs, controls: controls.filter(Boolean), createdAt: new Date().toISOString() };
+}
+
+// After a turn that could write, before git runs again: the repositories' own settings, hooks and
+// attributes as they were. Once per checkpoint; answers what was put back.
+export async function settleControls(checkpoint) {
+  if (!checkpoint || checkpoint.controlsSettled) return [];
+  checkpoint.controlsSettled = true;
+  const back = [];
+  for (const shot of checkpoint.controls ?? []) back.push(...await restoreControls(shot));
+  return back;
 }
 
 // What changed since the checkpoint: name-status per file and git's --stat.
 async function diffOne(root, before, prefix = '', exclude = []) {
-  const after = await worktreeTree(root, { exclude });
+  const via = before.via;
+  const after = await worktreeTree(root, { exclude, via });
   if (after === before.tree) return { files: [], stat: '' };
-  const nameStatus = await git(root, ['diff', '--name-status', '-M', before.tree, after]);
-  const files = nameStatus.split('\n').filter(Boolean).map((line) => {
+  const nameStatus = await git(root, ['diff', '--no-ext-diff', '--no-textconv', '--name-status', '-M', before.tree, after], { via });
+  const listed = nameStatus.split('\n').filter(Boolean).map((line) => {
     const [status, ...rest] = line.split('\t');
     const path = prefix + rest.at(-1);
-    return { status: status[0], path, from: status[0] === 'R' ? prefix + rest[0] : undefined };
+    return { status: status[0], path, inner: rest.at(-1), from: status[0] === 'R' ? prefix + rest[0] : undefined };
   });
-  const stat = (await git(root, ['diff', '--stat=100', before.tree, after])).trim();
+  // A file the turn taught git to ignore (a new .gitignore line) drops out of the second
+  // photograph while it is still on disk, untouched. That is not a deletion, and restoring it
+  // would report a write into a forbidden zone that never happened.
+  const files = [];
+  for (const file of listed) {
+    if (file.status === 'D' && await access(join(root, file.inner)).then(() => true, () => false)) continue;
+    files.push({ status: file.status, path: file.path, from: file.from });
+  }
+  if (!files.length) return { files: [], stat: '' };
+  const only = files.length < listed.length ? ['--', ...files.flatMap((file) => [file.path.slice(prefix.length), ...(file.from ? [file.from.slice(prefix.length)] : [])])] : [];
+  const stat = (await git(root, ['diff', '--no-ext-diff', '--no-textconv', '--stat=100', before.tree, after, ...only], { via })).trim();
   return { files, stat: prefix && stat ? stat.split('\n').map((line) => (line.startsWith(' ') ? ` ${prefix}${line.trimStart()}` : line)).join('\n') : stat };
 }
 
@@ -160,9 +244,9 @@ export async function diffCheckpoint(root, checkpoint) {
 // Which repository a project-relative path belongs to, and the path inside it.
 function repoFor(root, checkpoint, path) {
   for (const part of checkpoint.nested ?? []) {
-    if (path.startsWith(`${part.dir}/`)) return { dir: join(root, part.dir), commit: part.commit, inner: path.slice(part.dir.length + 1) };
+    if (path.startsWith(`${part.dir}/`)) return { dir: join(root, part.dir), commit: part.commit, via: part.via, inner: path.slice(part.dir.length + 1) };
   }
-  return { dir: root, commit: checkpoint.commit, inner: path };
+  return { dir: root, commit: checkpoint.commit, via: checkpoint.via, inner: path };
 }
 
 // Put the working tree back to the checkpoint: files added since are removed,
@@ -185,19 +269,37 @@ export async function restoreCheckpoint(root, checkpoint, { paths = null } = {})
       if (file.status === 'R' && file.from) {
         await unlink(absolute).catch(() => {});
         const origin = repoFor(root, checkpoint, file.from);
-        await git(origin.dir, ['restore', '--source', origin.commit, '--worktree', '--', origin.inner]);
+        await git(origin.dir, ['restore', '--source', origin.commit, '--worktree', '--', origin.inner], { via: origin.via });
         restored.push(file.from);
         removed.push(file.path);
         continue;
       }
-      await git(repo.dir, ['restore', '--source', repo.commit, '--worktree', '--', repo.inner]);
+      await git(repo.dir, ['restore', '--source', repo.commit, '--worktree', '--', repo.inner], { via: repo.via });
       restored.push(file.path);
     }
   }
+  await dropFoldersBornAfter(root, removed, Date.parse(checkpoint.createdAt));
   return { removed, restored };
 }
 
+// A folder the turn made for the files it added goes with them. Git keeps no folders, so after
+// UNDO an empty docs/ was the one trace left of a turn taken back. Only a folder born after the
+// checkpoint, deepest first, and only while it is empty: rmdir refuses anything else. Where the
+// system does not say when a folder was born, it stays.
+async function dropFoldersBornAfter(root, paths, since) {
+  if (!Number.isFinite(since) || !paths.length) return;
+  const canonicalRoot = resolve(root);
+  const folders = new Set();
+  for (const path of paths) {
+    for (let dir = dirname(resolve(root, path)); dir.startsWith(canonicalRoot + sep); dir = dirname(dir)) folders.add(dir);
+  }
+  for (const dir of [...folders].sort((a, b) => b.length - a.length)) {
+    const born = (await stat(dir).catch(() => null))?.birthtimeMs;
+    if (born > 0 && born >= since) await rmdir(dir).catch(() => {});
+  }
+}
+
 export async function dropCheckpoint(root, checkpoint) {
-  await git(root, ['update-ref', '-d', `${CHECKPOINT_REF}/${checkpoint.id}`]).catch(() => {});
-  for (const part of checkpoint.nested ?? []) await git(join(root, part.dir), ['update-ref', '-d', `${CHECKPOINT_REF}/${checkpoint.id}`]).catch(() => {});
+  await git(root, ['update-ref', '-d', `${CHECKPOINT_REF}/${checkpoint.id}`], { via: checkpoint.via }).catch(() => {});
+  for (const part of checkpoint.nested ?? []) await git(join(root, part.dir), ['update-ref', '-d', `${CHECKPOINT_REF}/${checkpoint.id}`], { via: part.via }).catch(() => {});
 }

package/src/choices.mjs

@@ -35,6 +35,10 @@ const MAX_OPTION = 320;
 
 const RECOMMENDED = /\s*[(\[]\s*(?:recommended|recomendad[ao]|sugerid[ao])\s*[)\]]\s*$/i;
 const STAR = /^[★☆⭐]\s*/;
+// The mode an option needs, written by the agent at its end: (#3), [#2 CREATE], #4. Below #1
+// nothing needs saying; an option that changes the project says which permission it will take,
+// so the human sees it before pressing rather than after the agent refuses.
+const MODE = /\s*[(\[]?\s*#([0-4])(?:\s+[A-Za-z]+)?\s*[)\]]?\s*$/;
 
 function clip(text, max) {
   if (text.length <= max) return text;
@@ -58,12 +62,21 @@ export function parseChoice(text) {
   const options = [];
   const seen = new Set();
   let recommended = null;
+  const modes = [];
   for (const line of lines.slice(question ? 1 : 0)) {
     const match = line.match(/^[-*•]\s+(.+)$/);
     if (!match) continue;
     let label = match[1].trim();
-    const marked = RECOMMENDED.test(label) || STAR.test(label);
-    label = clip(label.replace(RECOMMENDED, '').replace(STAR, '').trim(), MAX_OPTION);
+    // The two marks come in either order: «… (#3) (recommended)» or «… (recommended) #3».
+    let marked = STAR.test(label);
+    let mode = null;
+    label = label.replace(STAR, '');
+    for (let pass = 0; pass < 2; pass += 1) {
+      if (RECOMMENDED.test(label)) { marked = true; label = label.replace(RECOMMENDED, ''); }
+      const found = label.match(MODE);
+      if (found && mode === null) { mode = Number(found[1]); label = label.replace(MODE, ''); }
+    }
+    label = clip(label.trim(), MAX_OPTION);
     // The same option twice is a mistake, and a choice that offers it twice reads as rigged.
     const key = label.toLowerCase();
     if (!label || seen.has(key)) continue;
@@ -72,10 +85,12 @@ export function parseChoice(text) {
     // would punish the agent for the half it got right.
     if (marked && recommended === null) recommended = options.length;
     options.push(label);
+    modes.push(mode);
   }
   if (!question) return null;
   if (options.length < MIN_OPTIONS || options.length > MAX_OPTIONS) return null;
-  return { question, options, recommended };
+  // Modes travel only when an option has one: a choice that is all talk carries no column of nulls.
+  return { question, options, recommended, ...(modes.some((mode) => mode !== null) ? { modes } : {}) };
 }
 
 // What the reply reads as once the block has been lifted out of it: the room shows the question

package/src/cli-args.mjs

@@ -6,7 +6,13 @@
 export function parseArgs(argv) {
   const args = [...argv];
   const helpFlags = new Set(['help', '--help', '-h']);
-  const command = helpFlags.has(args[0])
+  // The first word is the command: `start` when there is none, or when the line opens with an
+  // option. `salas` (docs/MACROVERSO.md, D-S09) is one more word here; what it opens is decided
+  // beside the room of Salas, in src/salas.mjs.
+  // `named`: whether a command word was written at all. A bare `madre` (or `npx madre`) opens the
+  // lobby; `madre start` keeps opening the folder it is run in (src/salas.mjs, projectRootFor).
+  const named = Boolean(args[0]) && !args[0].startsWith('-') && !helpFlags.has(args[0]);
+  let command = helpFlags.has(args[0])
     ? 'help'
     : args[0]?.startsWith('-') ? 'start' : (args.shift() ?? 'start');
 
@@ -29,8 +35,13 @@ export function parseArgs(argv) {
       flags.add(name);
     }
   }
+  // `--help` after a command asks for the help, not for the command: `madre salas --help` prints
+  // what `salas` does instead of opening it. A value never starts with `-`, so `-h` on its own is
+  // never something an option was given.
+  if (flags.has('help') || args.includes('-h')) command = 'help';
   return {
     command,
+    named,
     option: (name, fallback) => options[name] ?? fallback,
     has: (name) => flags.has(name) || name in options,
     explicit: (name) => name in options,

package/src/commands.mjs

@@ -24,7 +24,7 @@ export const COMMANDS = [
   {
     name: 'git',
     module: 'git-pulse',
-    title: 'Git Pulse',
+    title: 'Git',
     usage: '/git [status|log|diff|branches|commit "message"|push [confirm]]',
     summary: 'Repository status, recent commits, uncommitted changes and branches from the project itself; commit and push by your own hand, with a confirmation before anything leaves.',
     async available({ projectRoot }) {
@@ -51,41 +51,41 @@ export const COMMANDS = [
       } else if (what === 'commit') {
         // The human commits what the room produced. Everything in the tree, one message, local: reversible with git.
         const message = args.slice(1).join(' ').replace(/^["'“]+|["'”]+$/g, '').trim();
-        if (!message) return { ok: false, title: 'Git Pulse · commit', text: 'Give the commit a message: /git commit "what and why".' };
+        if (!message) return { ok: false, title: 'Git · commit', text: 'Give the commit a message: /git commit "what and why".' };
         // Without an identity git refuses the commit with a wall of advice; say the one thing to do.
         const email = await run('git', ['config', '--get', 'user.email'], projectRoot);
         const who = await run('git', ['config', '--get', 'user.name'], projectRoot);
         if (!email.text.trim() || !who.text.trim()) {
-          return { ok: false, title: 'Git Pulse · commit', text: 'This computer has no git identity, so the commit would have no author. Set it once in your terminal:\n\n  git config --global user.name "Your Name"\n  git config --global user.email you@example.com' };
+          return { ok: false, title: 'Git · commit', text: 'This computer has no git identity, so the commit would have no author. Set it once in your terminal:\n\n  git config --global user.name "Your Name"\n  git config --global user.email you@example.com' };
         }
         const staged = await run('git', ['add', '-A', '--', '.'], projectRoot);
-        if (!staged.ok) return { ok: false, title: 'Git Pulse · commit', text: staged.text };
+        if (!staged.ok) return { ok: false, title: 'Git · commit', text: staged.text };
         const committed = await run('git', ['-c', 'color.ui=never', 'commit', '-m', message], projectRoot);
-        if (!committed.ok) return { ok: false, title: 'Git Pulse · commit', text: committed.text || 'Nothing to commit.' };
+        if (!committed.ok) return { ok: false, title: 'Git · commit', text: committed.text || 'Nothing to commit.' };
         await add('committed', ['-c', 'color.ui=never', 'show', '--stat', '--format=%h %s', 'HEAD']);
-        return { ok: true, title: 'Git Pulse · commit', text: sections.join('\n\n') };
+        return { ok: true, title: 'Git · commit', text: sections.join('\n\n') };
       } else if (what === 'push') {
         // Nothing leaves without the word: first the preview of what would go, then /git push confirm.
         const upstream = await run('git', ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], projectRoot);
-        if (!upstream.ok) return { ok: false, title: 'Git Pulse · push', text: `This branch has no upstream. Set it once from your terminal: git push -u <remote> <branch>.` };
+        if (!upstream.ok) return { ok: false, title: 'Git · push', text: `This branch has no upstream. Set it once from your terminal: git push -u <remote> <branch>.` };
         const ahead = await run('git', ['-c', 'color.ui=never', 'log', '--oneline', '@{u}..HEAD'], projectRoot);
         const commits = ahead.text ? ahead.text.split('\n').filter(Boolean) : [];
-        if (!commits.length) return { ok: true, title: 'Git Pulse · push', text: `Nothing to push: ${upstream.text} already has everything.` };
+        if (!commits.length) return { ok: true, title: 'Git · push', text: `Nothing to push: ${upstream.text} already has everything.` };
         if ((args[1] ?? '').toLowerCase() !== 'confirm') {
-          return { ok: true, title: 'Git Pulse · push · preview', text: `## would leave for ${upstream.text}\n${commits.join('\n')}\n\nThis leaves the machine and cannot be undone by MADRE. Send it with: /git push confirm` };
+          return { ok: true, title: 'Git · push · preview', text: `## would leave for ${upstream.text}\n${commits.join('\n')}\n\nThis leaves the machine and cannot be undone by MADRE. Send it with: /git push confirm` };
         }
         const pushed = await run('git', ['-c', 'color.ui=never', 'push'], projectRoot, 120000);
-        return { ok: pushed.ok, title: 'Git Pulse · push', text: `## sent to ${upstream.text}\n${commits.join('\n')}\n\n${pushed.text || '(pushed)'}` };
+        return { ok: pushed.ok, title: 'Git · push', text: `## sent to ${upstream.text}\n${commits.join('\n')}\n\n${pushed.text || '(pushed)'}` };
       } else {
-        return { ok: false, title: 'Git Pulse', text: `Unknown subcommand "${what}". Use /git status, /git log [n], /git diff, /git branches, /git commit "message" or /git push [confirm].` };
+        return { ok: false, title: 'Git', text: `Unknown subcommand "${what}". Use /git status, /git log [n], /git diff, /git branches, /git commit "message" or /git push [confirm].` };
       }
-      return { ok: true, title: `Git Pulse · ${what}`, text: sections.join('\n\n') };
+      return { ok: true, title: `Git · ${what}`, text: sections.join('\n\n') };
     },
   },
   {
     name: 'ahp',
     module: 'ahp',
-    title: 'AHP+',
+    title: 'Continuity',
     usage: '/ahp [status|check|context]',
     summary: 'Ask the AHP+ installed in this project for its verified status, checks or session context.',
     async available({ projectRoot }) {
@@ -98,9 +98,9 @@ export const COMMANDS = [
         check: ['project', 'check', '.'],
         context: ['session', 'context', '.', '--format', 'markdown', '--budget', '4000'],
       };
-      if (!map[what]) return { ok: false, title: 'AHP+', text: `Unknown subcommand "${what}". Use /ahp status, /ahp check or /ahp context.` };
+      if (!map[what]) return { ok: false, title: 'Continuity', text: `Unknown subcommand "${what}". Use /ahp status, /ahp check or /ahp context.` };
       const result = await run(join(projectRoot, 'node_modules', '.bin', 'ahp'), map[what], projectRoot, 60000);
-      return { ok: result.ok, title: `AHP+ · ${what}`, text: result.text || '(no output)' };
+      return { ok: result.ok, title: `Continuity · ${what}`, text: result.text || '(no output)' };
     },
   },
 ];