@jossuealcala/madre 0.7.1 → 0.7.2

package/src/modules/ollama.mjs

@@ -75,7 +75,11 @@ export default defineModule({
   },
   async updatePlan(ctx) {
     const { findOnPath } = await import('./helpers.mjs');
-    return ollamaUpdatePlan({ brew: await findOnPath('brew') });
+    const plan = ollamaUpdatePlan({ brew: await findOnPath('brew') });
+    if (!plan.command) return plan;
+    // Upgrading replaces the binary, not the server already running: until it restarts, the old
+    // version keeps answering. Said before the button is pressed, done after the command.
+    return { ...plan, note: `${plan.note} If an older Ollama is still the one answering, MADRE restarts it so the new one does.`, after: () => ctx.services.ollama.restart?.() ?? null };
   },
   async toggle(ctx) {
     const enabled = !(ctx.settings.enabled ?? true);

package/src/modules/runs.mjs

@@ -0,0 +1,34 @@
+// Runs: letting an agent ask the human to run a command instead of asking them to copy it.
+//
+// Below #4 AIRLOCK an agent cannot run anything, and some answers turn on a command anyway: the
+// tests after a fix, a build, a linter. This gives that request a shape — a fenced block the room
+// turns into one button per command — and brings the output back to the room as a card every
+// agent reads on its next turn.
+//
+// Nothing an agent writes runs by itself. Each line is pressed by the human, runs alone from the
+// project root with no shell, and is photographed first so UNDO can put the files back. What a
+// command sends off this machine does not come back with UNDO, and the button says what it runs
+// before it is pressed.
+//
+// It has a switch because it is not free: the instruction that teaches the block rides in every
+// prompt below AIRLOCK while this is on, measured in the economy as `runs`.
+
+import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.mjs';
+
+export default defineModule({
+  id: 'runs',
+  configKey: 'runs',
+  name: 'Runs',
+  vendor: 'MADRE',
+  version: '1.0.0',
+  summary: 'Lets an agent ask you to run a command it cannot run in its mode (tests, a build, a linter). Each command is a button: nothing runs until you press it, it runs from the project root with no shell, a checkpoint is taken first, and the output comes back to the room. Costs about 190 tokens of instruction per turn below AIRLOCK while it is on.',
+  creates: ['nothing in the project', 'a switch in ~/.pulse/config.json'],
+  async status(ctx) {
+    return {
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? t('on · agents may ask you to run commands') : t('off · agents describe the command in prose') },
+      install: { display: ctx.settings.enabled ? 'stop offering commands' : 'let agents ask for commands', platforms: [] },
+    };
+  },
+  async onToggle(ctx, enabled) { ctx.room.setRuns(enabled); return null; },
+});

package/src/ollama.mjs

@@ -28,6 +28,25 @@ function pick(models, preferred, env) {
   return names[0] ?? null;
 }
 
+// Two versions, and they are not the same thing. `ollama --version` names the server that answers
+// on the port and, when it differs, adds a warning with the client's own: that second one is what
+// is installed. An upgrade replaces the binary and leaves the old server running — and that old
+// server then starts the NEW runner, which is how a model load ends in `invalid argument`.
+export function ollamaVersions(output) {
+  const text = String(output ?? '');
+  const server = text.match(/ollama version is\s+(\S+)/i)?.[1] ?? null;
+  const client = text.match(/client version is\s+(\S+)/i)?.[1] ?? server;
+  return { server, client };
+}
+
+// The `ollama serve` processes this user owns. Only those: an Ollama app, or a system service
+// running as another user, is not MADRE's to stop, and the room says so instead.
+export function ownOllamaServers(psOutput, uid) {
+  return String(psOutput ?? '').split('\n').map((line) => line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/)).filter(Boolean)
+    .filter(([, , owner, args]) => Number(owner) === uid && /(^|\/)ollama serve$/.test(args.trim()))
+    .map(([, pid]) => Number(pid));
+}
+
 // Is Ollama there, and what can it do? Quick, never throws.
 export async function probeOllama({ host = ollamaHost(), fetchImpl = globalThis.fetch, timeoutMs = 1500, env = process.env } = {}) {
   try {

package/src/room/control.mjs

@@ -75,11 +75,28 @@ export class ControlDesk {
     if (this.#holder === run) this.#holder = null;
   }
 
+  // A photograph with no seat and no locks, for a command the human runs by hand: the human may
+  // write anywhere, so nothing is guarded and nothing is reverted, but UNDO still has a place to
+  // go back to. The same map as CONTROL's, so the same UNDO restores it.
+  async photograph({ id, label, by = 'you', command = null }) {
+    const checkpoint = await createCheckpoint(this.#projectRoot, { id, label });
+    checkpoint.agent = by;
+    checkpoint.command = command;
+    this.#checkpoints.set(checkpoint.id, checkpoint);
+    return checkpoint;
+  }
+
+  async changesSince(checkpoint) {
+    const { files, stat } = await diffCheckpoint(this.#projectRoot, checkpoint);
+    return { files, stat };
+  }
+
   async undo(checkpointId) {
     const checkpoint = this.#checkpoints.get(checkpointId);
     if (!checkpoint) return { ok: false, status: 404, error: 'That checkpoint is not known to this room.' };
     if (this.#holder?.checkpoint.id === checkpointId) return { ok: false, status: 409, error: 'That CONTROL turn is still running; STOPALL first.' };
     const result = await restoreCheckpoint(this.#projectRoot, checkpoint);
-    return { ok: true, checkpoint, ...result, message: `Project restored to the checkpoint taken before @${checkpoint.agent}'s CONTROL turn: ${result.restored.length} file(s) restored, ${result.removed.length} removed.` };
+    const before = checkpoint.command ? `\`${checkpoint.command}\`` : `@${checkpoint.agent}'s CONTROL turn`;
+    return { ok: true, checkpoint, ...result, message: `Project restored to the checkpoint taken before ${before}: ${result.restored.length} file(s) restored, ${result.removed.length} removed.` };
   }
 }

package/src/room/prompt.mjs

@@ -40,13 +40,15 @@ export const BLOCK_SOURCES = {
   recall: { when: 'older exchanges match the request and fit in the budget', where: '⚙ CONNECTIONS → MEMORY · RECALL · % OF CONTEXT' },
   context: { when: 'the room has a transcript', where: 'PULSE_CONTEXT_MAX_CHARS sets the budget; RECALL · % OF CONTEXT splits it' },
   delegation: { when: 'this turn may open a plan', where: '⚙ CONNECTIONS → ROOM SETTINGS → DELEGATION' },
+  choices: { when: 'Choices is on and the turn is not GHOST', where: 'MODULES → CHOICES' },
+  runs: { when: 'Runs is on and the turn is #1 to #3', where: 'MODULES → RUNS' },
   abilities: { when: 'this turn may open a plan', where: '⚙ CONNECTIONS → each agent\'s abilities and MAX MODE' },
   attachments: { when: 'the message carries attached files', where: null },
   references: { when: 'the message points at project files with !', where: null },
   ask: { when: 'the human is the one asking', where: null },
 };
 
-export const PROMPT_BLOCKS = ['room', 'who', 'style', 'privacy', 'madre', 'memory-server', 'mode', 'inspect', 'ash', 'mother', 'mcp', 'sdk', 'lease', 'control-held', 'escalation', 'web', 'shared-lease', 'memories', 'recall', 'context', 'delegation', 'abilities', 'attachments', 'references', 'ask'];
+export const PROMPT_BLOCKS = ['room', 'who', 'style', 'privacy', 'madre', 'memory-server', 'mode', 'inspect', 'ash', 'mother', 'mcp', 'sdk', 'lease', 'control-held', 'escalation', 'web', 'shared-lease', 'memories', 'recall', 'context', 'delegation', 'choices', 'runs', 'abilities', 'attachments', 'references', 'ask'];
 
 // Whether this turn could plausibly produce a MADRE module. The SDK block is long and is only
 // ever of use when the human is asking for one, so it is not carried by every leased turn. The
@@ -69,7 +71,7 @@ export function sparedChars(options) {
 export function promptParts({
   agent, text, requester, depth, allowDelegation, context, recall = null, memories = null,
   attachments = [], references = [], lease = null, scopes = null, imageStudio = null,
-  sharedLeaseHint = null, ash = false, choices = false, mode = 1, escalation = null, mcpServers = [],
+  sharedLeaseHint = null, ash = false, choices = false, runs = false, mode = 1, escalation = null, mcpServers = [],
   // What the room adds:
   others = [], delegation = true, maxPlanSteps = 4, scopesFor = () => ({}), motherLines = [], memoryServer = null, controlHolder = null, privacyMarker = '[ENTIDAD-ORG]', madreModel = null, sdk = null,
 }) {
@@ -128,11 +130,21 @@ export function promptParts({
         'If answering well means the human has to pick between three or more real options, end your reply with one fenced block:',
         '```pulse-ask',
         '<the question, one line>',
+        '- <the option you would pick> (recommended)',
         '- <option>',
         '- <option>',
-        '- <option>',
         '```',
-        'Three to six options, the question first, nothing after the block. MADRE shows them as buttons and pressing one writes it into the composer; nothing runs and no turn is spent until the human presses. Not for yes/no, and never instead of a recommendation you could simply give.',
+        'Three to six options, the question first, nothing after the block. Exactly one option ends with "(recommended)": the one you would pick, listed first. Write each option whole, as the sentence the human would send; they are shown in full. MADRE shows them as buttons and pressing one writes it into the composer; nothing runs and no turn is spent until the human presses. Not for yes/no, and never instead of a recommendation you could simply give.',
+      ].join('\n')
+      : null },
+    { id: 'runs', text: runs
+      ? [
+        'You cannot run commands in this mode. If your answer depends on one (tests, a build, a linter, a git query), end your reply with one fenced block and the human may run it for you:',
+        '```pulse-run',
+        '<why you need it, one line>',
+        '$ <command>',
+        '```',
+        `The reason first, then one command per line, each starting with "$", at most 5, nothing after the block. There is no shell: each line runs alone from the project root, so no pipes, &&, redirections, $VARIABLES, globs, ~ or cd. Quote arguments with spaces. MADRE shows each line as a button; nothing runs until the human presses it, and its output comes back to the room for your next turn. Ask only for what you cannot learn by reading the files, and never for something that changes what lives outside this machine.`,
       ].join('\n')
       : null },
     { id: 'abilities', text: mayDelegate ? `Abilities right now (route each step to an agent that can do it):\n${[agent.id, ...others].map((id) => abilityLine(id, scopesFor(id))).join('\n')}` : null },

package/src/room/runs.mjs

@@ -0,0 +1,88 @@
+// The human's hands for a command an agent asked for. One command at a time, in the project
+// root, with no shell: the argv the parser split is the argv that runs (see src/runs.mjs).
+//
+// stdin is closed, so a program that wants to ask something reads end-of-file and gives up
+// instead of hanging on a prompt nobody can see. The output is one stream, stdout and stderr
+// interleaved the way a terminal shows them, and what is kept of a long one is its start and its
+// end: a test run says what it is at the top and how it went at the bottom.
+
+import { spawn } from 'node:child_process';
+import { terminateProcessTree } from '../adapters/process.mjs';
+
+export const RUN_TIMEOUT_MS = 10 * 60 * 1000;
+const HEAD_CHARS = 4000;
+const TAIL_CHARS = 14000;
+
+export function keepEnds(text, { head = HEAD_CHARS, tail = TAIL_CHARS } = {}) {
+  if (text.length <= head + tail) return text;
+  const dropped = text.length - head - tail;
+  return `${text.slice(0, head)}\n… ${dropped} characters of output left out …\n${text.slice(-tail)}`;
+}
+
+export class RunDesk {
+  #child = null;
+  #stoppedBy = null;
+
+  get busy() { return Boolean(this.#child); }
+
+  // Resolves with what happened; never rejects. A program that could not start is an answer too.
+  run({ argv, cwd, timeoutMs = RUN_TIMEOUT_MS, env = process.env }) {
+    return new Promise((resolve) => {
+      const started = Date.now();
+      // 'error' and 'close' can both arrive for one failed spawn; the first one is the answer.
+      let settled = false;
+      const done = (result) => {
+        if (settled) return;
+        settled = true;
+        this.#child = null;
+        resolve({ ...result, durationMs: Date.now() - started });
+      };
+      let child;
+      try {
+        child = spawn(argv[0], argv.slice(1), {
+          cwd,
+          env: { ...env, NO_COLOR: '1', FORCE_COLOR: '0', GIT_PAGER: 'cat', PAGER: 'cat' },
+          stdio: ['ignore', 'pipe', 'pipe'],
+          shell: false,
+          detached: process.platform !== 'win32',
+          windowsHide: true,
+        });
+      } catch (error) {
+        done({ ok: false, exitCode: null, text: couldNotRun(argv[0], error) });
+        return;
+      }
+      this.#child = child;
+      this.#stoppedBy = null;
+      let output = '';
+      // Bounded while it runs, not only at the end: a program that prints without stopping must
+      // not grow the server's memory for ten minutes.
+      const take = (chunk) => {
+        output += chunk;
+        if (output.length > (HEAD_CHARS + TAIL_CHARS) * 2) output = keepEnds(output);
+      };
+      child.stdout.on('data', take);
+      child.stderr.on('data', take);
+      const timer = setTimeout(() => { this.#stoppedBy = `timeout (${Math.round(timeoutMs / 1000)}s)`; terminateProcessTree(child); }, timeoutMs);
+      timer.unref?.();
+      child.on('error', (error) => { clearTimeout(timer); done({ ok: false, exitCode: null, text: couldNotRun(argv[0], error) }); });
+      child.on('close', (code, signal) => {
+        clearTimeout(timer);
+        const stoppedBy = this.#stoppedBy;
+        const tail = stoppedBy ? `\n[stopped: ${stoppedBy}]` : signal ? `\n[ended on ${signal}]` : code !== 0 ? `\n[exit code ${code}]` : '';
+        done({ ok: code === 0 && !stoppedBy, exitCode: code, signal: signal ?? undefined, stoppedBy: stoppedBy ?? undefined, text: `${keepEnds(output).trimEnd()}${tail}`.trim() });
+      });
+    });
+  }
+
+  stop(reason = 'STOPALL') {
+    if (!this.#child) return false;
+    this.#stoppedBy = reason;
+    terminateProcessTree(this.#child);
+    return true;
+  }
+}
+
+function couldNotRun(program, error) {
+  if (error?.code === 'ENOENT') return `${program} could not start: it is not installed, or not on the PATH MADRE was started with.`;
+  return `${program} could not start: ${error?.message ?? error}`;
+}

package/src/room.mjs

@@ -17,6 +17,7 @@ import { coverageExam, consistencyExam, matchExam, exchanges, MATCH_SAMPLE, says
 import { MADRE_ADAPTER, MADRE_AGENT_ID } from './adapters/madre.mjs';
 import { verdictFor } from './verdict.mjs';
 import { ControlDesk } from './room/control.mjs';
+import { RunDesk } from './room/runs.mjs';
 import { Attachments } from './room/attachments.mjs';
 import { GhostLedger } from './room/ghost.mjs';
 import { Escalation } from './room/escalation.mjs';
@@ -27,7 +28,7 @@ import { OLLAMA_ARCHIVIST } from './distiller.mjs';
 import { memoryServerForTurn } from './memory-tools.mjs';
 import { CODE000_STRIKES } from './mother.mjs';
 import { parseDirectives } from './directives.mjs';
-import { isValidModelName } from './models.mjs';
+import { isValidModelName, isValidEffort } from './models.mjs';
 import { MODES, SCOPES, SCOPE_LABELS, capabilitySummary, normalizeMode, resolveScopes } from './capabilities.mjs';
 import { createLease, diffSnapshots, namedPaths, snapshot } from './lease.mjs';
 import { stat as statFile } from 'node:fs/promises';
@@ -36,6 +37,7 @@ import { contentTypeFor } from './files.mjs';
 import { isModuleFile, sdkPaths } from './modules/index.mjs';
 import { validateAshReply } from './modules/ash-policy.mjs';
 import { parseChoice, withoutChoice } from './choices.mjs';
+import { parseRunRequest, withoutRunRequest, whyText } from './runs.mjs';
 import { imageStudioFor } from './image-studio.mjs';
 import { CAPABILITIES, imageModuleState } from './capabilities.mjs';
 import { resolveReferences } from './files.mjs';
@@ -134,6 +136,9 @@ export class Room {
   #planMaxAgeMs;
   #ashEnabled = false;
   #choicesEnabled = false;
+  #runsEnabled = false;
+  #runDesk = new RunDesk();
+  #runBusy = false;
 
   constructor({
     store,
@@ -228,7 +233,7 @@ export class Room {
     const result = await this.#controlDesk.undo(checkpointId);
     if (!result.ok) return result;
     const { checkpoint, message, ...rest } = result;
-    await this.#emit('control.reverted', { checkpointId, agent: checkpoint.agent, removed: rest.removed, restored: rest.restored, message });
+    await this.#emit('control.reverted', { checkpointId, agent: checkpoint.agent, command: checkpoint.command ?? undefined, removed: rest.removed, restored: rest.restored, message });
     return { ok: true, ...rest };
   }
 
@@ -764,6 +769,53 @@ export class Room {
     return this.#choicesEnabled;
   }
 
+  setRuns(enabled) {
+    this.#runsEnabled = Boolean(enabled);
+    return this.#runsEnabled;
+  }
+
+  runsEnabled() {
+    return this.#runsEnabled;
+  }
+
+  // The human pressed one line of a ```pulse-run an agent wrote. The client names the request and
+  // the line, never the command: what runs is read back from the room's own record of what the
+  // agent asked, so a page cannot run anything that was not shown to the human as a button.
+  async runRequested({ responseMessageId, index }) {
+    if (!this.#runsEnabled) return { ok: false, status: 412, error: 'Command requests are off. Enable them in MODULES.' };
+    const events = await this.#store.readAll();
+    const request = events.find((event) => event.type === 'run.requested' && event.payload.responseMessageId === responseMessageId)?.payload;
+    const command = request?.commands?.[index];
+    if (!command) return { ok: false, status: 404, error: 'That command request is not in this room.' };
+    if (!command.argv) return { ok: false, status: 422, error: `That line does not run: it ${whyText(command)}.` };
+    if (this.#runBusy) return { ok: false, status: 409, error: 'A command is already running; wait for it or STOPALL.' };
+    if (this.#controlDesk.holder) return { ok: false, status: 409, error: `@${this.#controlDesk.holder.agent} holds ${MODES[this.#controlDesk.holder.mode ?? 3].label} of this project; run it when the turn ends.` };
+    // Taken before the first await below: two presses in a row must not both get through.
+    this.#runBusy = true;
+    try { return await this.#runCommand({ request, command, responseMessageId, index }); } finally { this.#runBusy = false; }
+  }
+
+  async #runCommand({ request, command, responseMessageId, index }) {
+    const run = { responseMessageId, index, agent: request.agent, line: command.line };
+    await this.#emit('run.started', run);
+    let checkpoint = null;
+    try {
+      checkpoint = await this.#controlDesk.photograph({ id: `${new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14)}-run-${responseMessageId.slice(0, 8)}-${index}`, label: `MADRE run @${request.agent}`, command: command.line });
+    } catch { /* no photograph, no UNDO: the command still runs, and the card says so */ }
+    const result = await this.#runDesk.run({ argv: command.argv, cwd: this.#projectRoot });
+    const changes = checkpoint ? await this.#controlDesk.changesSince(checkpoint).catch(() => null) : null;
+    const status = result.stoppedBy ? `stopped (${result.stoppedBy})` : result.exitCode === null ? 'did not start' : `exit ${result.exitCode}`;
+    const event = await this.#emit('command.output', {
+      name: 'run',
+      title: `$ ${command.line} · ${status} · ${(result.durationMs / 1000).toFixed(1)}s · asked by @${request.agent}`,
+      text: `${result.text || '(no output)'}${changes?.files.length ? `\n\nFiles changed: ${changes.files.map((file) => `${file.status} ${file.path}`).join(', ')}` : ''}`,
+      ok: result.ok,
+      args: [],
+      run: { ...run, exitCode: result.exitCode, durationMs: result.durationMs, stoppedBy: result.stoppedBy, checkpointId: checkpoint?.id, files: changes?.files.length ? changes.files.slice(0, 40) : undefined },
+    });
+    return { ok: true, status: 200, result: { ok: result.ok, exitCode: result.exitCode, sequence: event.sequence } };
+  }
+
   ashEnabled() {
     return this.#ashEnabled;
   }
@@ -840,7 +892,7 @@ export class Room {
     this.#vectors.stop();
   }
 
-  async send({ text, target, model = null, attachments = [], create = false, ash = false, mode = undefined }) {
+  async send({ text, target, model = null, effort = null, attachments = [], create = false, ash = false, mode = undefined }) {
     const parsed = parseMessage(text, target);
     const requestedMode = normalizeMode(mode, create === true ? 2 : 1);
     // This is the decision the human made when pressing Send. Capture it before modeCheck() —
@@ -857,6 +909,9 @@ export class Room {
     if (!parsed.target) throw new Error('Choose an agent or begin with @agent.');
     if (model !== null && model !== undefined && model !== '' && !isValidModelName(model)) throw new Error('Model name is not valid.');
     const chosenModel = model || null;
+    // An effort the target's CLI does not take is dropped, not refused: the composer remembers it
+    // per agent, so a stale one should cost the human nothing but the flag.
+    const chosenEffort = isValidEffort(parsed.target, effort) ? effort : null;
     // What the human wrote, sent as they wrote it. Ash used to rewrite this line before it left
     // the room; it does not any more, so there is no original to keep beside an abbreviation.
     const text2 = parsed.text || `(${files.length} attached file${files.length === 1 ? '' : 's'})`;
@@ -877,6 +932,7 @@ export class Room {
       ash: ashRequested ? { requested: true, active: ashActive } : undefined,
       status: 'sent',
       model: chosenModel,
+      effort: chosenEffort ?? undefined,
       attachments: files.length ? files.map((file) => ({ id: file.id, name: file.name, fileName: file.fileName, size: file.size, contentType: file.contentType })) : undefined,
       references: references.length ? references.map(({ excerpt, ...reference }) => reference) : undefined,
       create: create === true ? true : undefined,
@@ -941,7 +997,7 @@ export class Room {
       allowDelegation = false;
       await this.#alert('plan-active', `A plan by @${[...this.#plans.values()][0].orchestrator} is still running. Your message will be answered, but no second plan will start. Type STOPALL to halt every agent.`, `plan-active:${messageId}`);
     }
-    await this.#track(this.#dispatch({ messageId, targetId: parsed.target, text: text2, requester: 'you', depth: 0, allowDelegation: allowDelegation && !ghost, model: chosenModel, attachments: files, references, lease, ash: ashActive, mode: ghost ? 0 : control ? requestedMode : (lease ? 2 : 1) }));
+    await this.#track(this.#dispatch({ messageId, targetId: parsed.target, text: text2, requester: 'you', depth: 0, allowDelegation: allowDelegation && !ghost, model: chosenModel, effort: chosenEffort, attachments: files, references, lease, ash: ashActive, mode: ghost ? 0 : control ? requestedMode : (lease ? 2 : 1) }));
   }
 
   // A #2 lease: the project itself is where new files go, and MADRE keeps a scratch folder
@@ -983,6 +1039,7 @@ export class Room {
     for (const plan of this.#plans.values()) plan.stopped = reason;
     this.#escalation.settleAll(null, 'stopped');
     for (const turn of this.#turns.values()) turn.controller.abort(reason);
+    this.#runDesk.stop('STOPALL');
     await this.#emit('room.stopped', { reason, plans, turns, agents: [...new Set([...this.#turns.values()].map((turn) => turn.agent))] });
     await Promise.allSettled([...this.#turns.values()].map((turn) => turn.promise));
     return { plans, turns };
@@ -1032,7 +1089,7 @@ export class Room {
 
   // One room turn for one agent. `requester` is who asked ('you' or an
   // orchestrating agent); `depth` 0 turns may delegate, deeper ones may not.
-  async #dispatch({ messageId, targetId, text, requester, depth, planId = null, allowDelegation = true, model = null, attachments = [], references = [], lease = null, ash = false, mode = 1, escalation = null }) {
+  async #dispatch({ messageId, targetId, text, requester, depth, planId = null, allowDelegation = true, model = null, effort = null, attachments = [], references = [], lease = null, ash = false, mode = 1, escalation = null }) {
     if (this.#shuttingDown) return null;
     const agent = this.#agents.find((item) => item.id === targetId);
     if (!agent?.detected) {
@@ -1089,7 +1146,7 @@ export class Room {
     await this.#emit('agent.started', { messageId, agent: agent.id, handoffId, planId });
     const controller = new AbortController();
     const turn = { controller, promise: null, planId, agent: agent.id, startedAt: Date.now() };
-    turn.promise = this.#runTurn({ messageId, agent, text, requester, depth, planId, allowDelegation, context, recall, memories, handoffId, signal: controller.signal, model, attachments, references, lease, ash, mode, escalation });
+    turn.promise = this.#runTurn({ messageId, agent, text, requester, depth, planId, allowDelegation, context, recall, memories, handoffId, signal: controller.signal, model, effort, attachments, references, lease, ash, mode, escalation });
     this.#turns.set(messageId, turn);
     let outcome = null;
     try {
@@ -1145,7 +1202,7 @@ export class Room {
       context: built.context, recall: built.recall, memories: built.memories,
       attachments: [], references: [], lease,
       scopes: { web: scopes.web.enabled && scopes.web.wired, imageGen: scopes.imageGen.enabled && scopes.imageGen.wired },
-      ash: ash === true && this.ashEnabled(), mode, escalation: null, mcpServers,
+      ash: ash === true && this.ashEnabled(), choices: this.#choicesEnabled && mode !== 0, runs: this.#runsEnabled && mode !== 0 && mode < 4, mode, escalation: null, mcpServers,
     });
     // Each block with what put it here and what would take it away, so "read, never written" can
     // be checked one block at a time instead of believed.
@@ -1244,7 +1301,7 @@ export class Room {
     });
   }
 
-  async #runTurn({ messageId, agent, text, requester, depth, planId, allowDelegation, context, recall = null, memories = null, handoffId, signal, model = null, attachments = [], references = [], lease: sharedLease = null, ash = false, mode = 1, escalation = null }) {
+  async #runTurn({ messageId, agent, text, requester, depth, planId, allowDelegation, context, recall = null, memories = null, handoffId, signal, model = null, effort = null, attachments = [], references = [], lease: sharedLease = null, ash = false, mode = 1, escalation = null }) {
     // The lease is the human's; what each agent may do inside it is that
     // agent's own enabled scopes. A delegate without file creation runs
     // read-only even while the plan holds a lease.
@@ -1337,7 +1394,7 @@ export class Room {
         : [];
       // The prompt and the shape it was built from: one is sent, the other is kept until the CLI
       // says what it cost, so the bill can be attributed to the blocks that caused it.
-      const shaped = this.#promptFor({ agent, text, requester, depth, allowDelegation, context, recall, memories, attachments, references, lease, scopes: turnScopes, imageStudio, ash, choices: this.#choicesEnabled, mode: turnMode, escalation, mcpServers, sharedLeaseHint: sharedLease && !lease ? 'A creation lease is active for this plan, but file creation is not enabled for you: answer without creating files and say so if asked to create one.' : null });
+      const shaped = this.#promptFor({ agent, text, requester, depth, allowDelegation, context, recall, memories, attachments, references, lease, scopes: turnScopes, imageStudio, ash, choices: this.#choicesEnabled && turnMode !== 0, runs: this.#runsEnabled && turnMode !== 0 && turnMode < 4, mode: turnMode, escalation, mcpServers, sharedLeaseHint: sharedLease && !lease ? 'A creation lease is active for this plan, but file creation is not enabled for you: answer without creating files and say so if asked to create one.' : null });
       this.#promptShape.set(responseMessageId, { parts: shaped.parts, spared: shaped.spared });
       // What this turn is about to read, said while it is still reading it. The size is exact;
       // only the conversion to tokens is an estimate, and it is made at this room's own rate.
@@ -1361,6 +1418,7 @@ export class Room {
         timeoutMs: this.timeoutFor(agent.id),
         signal,
         model,
+        effort,
         attachments,
         lease,
         scopes: turnScopes,
@@ -1410,13 +1468,15 @@ export class Room {
       }
       // A question the agent put to the human: it leaves the text and comes back as buttons.
       const asked = this.#choicesEnabled && turnMode !== 0 ? parseChoice(result.text) : null;
+      // Commands it wants the human to run: the same, as buttons. AIRLOCK runs its own.
+      const requested = !asked && this.#runsEnabled && turnMode !== 0 && turnMode < 4 ? parseRunRequest(result.text) : null;
       await this.#emit('message.created', {
         messageId: responseMessageId,
         parentMessageId: messageId,
         role: 'assistant',
         sender: agent.id,
         target: requester,
-        text: asked ? withoutChoice(result.text) : result.text,
+        text: asked ? withoutChoice(result.text) : requested ? withoutRunRequest(result.text) : result.text,
         // What the archive handed this turn, so the room can see its own memory working. The
         // whole point of remembering is invisible until the moment it is used.
         recalled: memories?.length
@@ -1426,6 +1486,7 @@ export class Room {
         status: 'completed',
         planId,
         model,
+        effort: effort ?? undefined,
         synthetic: result.synthetic || undefined,
         redacted: guarded.hits || undefined,
         mode: turnMode,
@@ -1437,7 +1498,8 @@ export class Room {
         const validation = validateAshReply({ request: text, response: result.text });
         await this.#emit('ash.validated', { messageId, responseMessageId, agent: agent.id, ...validation });
       }
-      if (asked) await this.#emit('choice.offered', { messageId, responseMessageId, agent: agent.id, question: asked.question, options: asked.options });
+      if (asked) await this.#emit('choice.offered', { messageId, responseMessageId, agent: agent.id, question: asked.question, options: asked.options, recommended: asked.recommended ?? undefined });
+      if (requested) await this.#emit('run.requested', { messageId, responseMessageId, agent: agent.id, reason: requested.reason, commands: requested.commands });
       if (guarded.hits) await this.#emit('privacy.redacted', { agent: agent.id, messageId, responseMessageId, hits: guarded.hits, marker: this.#privacy.marker });
       if (artifacts.length) {
         await this.#emit('artifacts.created', { leaseId: lease.leaseId, messageId, responseMessageId, agent: agent.id, outDir: lease.relativeDir, files: artifacts });

package/src/runs.mjs

@@ -0,0 +1,119 @@
+// An agent asking the human to run a command.
+//
+// Below #4 AIRLOCK no agent runs anything: it reads, it writes where its mode allows, and that is
+// all. Some answers still turn on a command — the tests after a fix, a build, a linter — and the
+// agent used to say "run npm test and tell me", leaving the human to copy it into a terminal and
+// paste the output back. This gives the request a shape. ```pulse-run carries the reason and the
+// commands; MADRE shows each one as a button; the human presses; the output lands in the room as
+// a card every agent reads on its next turn.
+//
+// Inert, like ```pulse-ask: parsing it runs nothing. The press is the human's, line by line.
+//
+//   ```pulse-run
+//   Check that the fix did not break the parser
+//   $ npm test
+//   $ node --check src/runs.mjs
+//   ```
+//
+// One command per line, and no shell. A line becomes an argv the way a POSIX shell would split
+// it — quotes and backslashes — and nothing else: no pipes, no `&&`, no redirections, no `$VAR`,
+// no globs. Without a shell those would arrive at the program as literal characters and do
+// something other than what the human read on the button, so a line that has one is refused and
+// says why. Running it through a shell instead would hand an agent's text to `sh` or `cmd.exe`
+// (WIN-016): the human approves a line, and the line that runs has to be the one they read.
+
+export const MAX_COMMANDS = 5;
+const MAX_REASON = 300;
+const MAX_LINE = 500;
+
+// Shell builtins: without a shell they are not programs, or they are programs that change nothing.
+const BUILTINS = new Set(['cd', 'export', 'source', '.', 'alias', 'unset', 'set', 'eval', 'exec', 'pushd', 'popd']);
+
+function clip(text, max) {
+  return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+
+// A line split into words the way sh would, without anything sh would expand. Returns
+// { argv } or { why } when the line needs a shell to mean what it says.
+export function splitCommand(line) {
+  const argv = [];
+  let word = '';
+  let inWord = false;
+  let quote = null;
+  for (let i = 0; i < line.length; i += 1) {
+    const char = line[i];
+    if (quote === "'") {
+      if (char === "'") quote = null; else word += char;
+      continue;
+    }
+    if (quote === '"') {
+      if (char === '"') { quote = null; continue; }
+      if (char === '\\' && i + 1 < line.length && '"\\$`'.includes(line[i + 1])) { word += line[i + 1]; i += 1; continue; }
+      if (char === '$' || char === '`') return { why: 'expands a variable or a command inside quotes; there is no shell to expand it' };
+      word += char;
+      continue;
+    }
+    if (char === "'" || char === '"') { quote = char; inWord = true; continue; }
+    if (char === '\\') {
+      if (i + 1 < line.length) { word += line[i + 1]; i += 1; inWord = true; continue; }
+      return { why: 'ends in a lone backslash' };
+    }
+    if (/\s/.test(char)) {
+      if (inWord) { argv.push(word); word = ''; inWord = false; }
+      continue;
+    }
+    if ('|&;<>()'.includes(char)) return { why: 'uses "{char}", which needs a shell; put each command on its own line', whyArgs: { char } };
+    if (char === '$' || char === '`') return { why: 'expands a variable or a command; there is no shell to expand it' };
+    if (char === '*' || char === '?' || char === '[') return { why: 'uses "{char}" as a glob; there is no shell to expand it, name the files', whyArgs: { char } };
+    if (char === '~' && !inWord) return { why: 'starts a word with "~"; there is no shell to expand it, write the path' };
+    if (char === '#' && !inWord) return { why: 'carries a "#" comment, which only a shell would drop; say it in the reason' };
+    word += char;
+    inWord = true;
+  }
+  if (quote) return { why: 'leaves a quote open' };
+  if (inWord) argv.push(word);
+  if (!argv.length) return { why: 'is empty' };
+  if (BUILTINS.has(argv[0])) return { why: '"{name}" is a shell builtin; every line already runs from the project root', whyArgs: { name: argv[0] } };
+  if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(argv[0])) return { why: 'sets an environment variable, which needs a shell' };
+  return { argv };
+}
+
+// A refusal is a template so the room can say it in the human's language; this fills it in.
+export const whyText = (command) => String(command?.why ?? '').replace(/\{(\w+)\}/g, (match, key) => command?.whyArgs?.[key] ?? match);
+
+// The last ```pulse-run block of a reply, if it closes the reply. Returns null for anything else:
+// a block quoted mid-answer is an example, and an example is not a request.
+export function parseRunRequest(text) {
+  const source = String(text ?? '');
+  const blocks = [...source.matchAll(/```pulse-run\s*\n([\s\S]*?)```/gi)];
+  if (!blocks.length) return null;
+  const last = blocks.at(-1);
+  if (source.slice(last.index + last[0].length).trim()) return null;
+
+  const lines = last[1].split('\n').map((line) => line.trim()).filter(Boolean);
+  const reason = lines[0] && !lines[0].startsWith('$') ? clip(lines[0], MAX_REASON) : null;
+  const commands = [];
+  const seen = new Set();
+  for (const raw of lines.slice(reason ? 1 : 0)) {
+    if (!raw.startsWith('$')) continue;
+    const line = raw.slice(1).trim();
+    if (!line || seen.has(line)) continue;
+    seen.add(line);
+    if (commands.length === MAX_COMMANDS) break;
+    if (line.length > MAX_LINE) { commands.push({ line: clip(line, MAX_LINE), why: 'is too long to read before pressing it' }); continue; }
+    const split = splitCommand(line);
+    commands.push(split.argv ? { line, argv: split.argv } : { line, why: split.why, ...(split.whyArgs ? { whyArgs: split.whyArgs } : {}) });
+  }
+  // A request without a reason asks the human to run something on faith.
+  if (!reason || !commands.length) return null;
+  return { reason, commands };
+}
+
+// What the reply reads as once the block has been lifted out of it: the room shows the commands
+// as buttons, so leaving the raw fence in the text would say everything twice.
+export function withoutRunRequest(text) {
+  const source = String(text ?? '');
+  if (!parseRunRequest(source)) return source;
+  const last = [...source.matchAll(/```pulse-run\s*\n[\s\S]*?```/gi)].at(-1);
+  return source.slice(0, last.index).trimEnd();
+}