@jossuealcala/madre 1.0.0 → 1.0.2

package/src/room.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 import { invokeCodex, buildCodexArgs } from './adapters/codex.mjs';
 import { t } from './i18n.mjs';
 import { invokeClaude, buildClaudeArgs } from './adapters/claude.mjs';
@@ -34,12 +36,14 @@ import { MODES, SCOPES, SCOPE_LABELS, capabilitySummary, normalizeMode, resolveS
 import { createLease, diffSnapshots, namedPaths, snapshot } from './lease.mjs';
 import { stat as statFile, readdir, copyFile, readFile as readFileBytes } from 'node:fs/promises';
 import { basename as baseName, join as joinPath } from 'node:path';
-import { declaredTypeFor } from './files.mjs';
+import { declaredTypeFor, filesChangedSince } from './files.mjs';
 import { isModuleFile, sdkPaths } from './modules/index.mjs';
 import { validateAshReply } from './modules/ash-policy.mjs';
 import { PHONE_MAX_MODE } from './bridge/policy.mjs';
 import { parseChoice, withoutChoice } from './choices.mjs';
 import { parseRunRequest, withoutRunRequest, whyText, expandHome } from './runs.mjs';
+import { runSettlement, returnedBlock } from './room/returns.mjs';
+import { copilotSafe, copilotBrief, COPILOT_MAX_ROUNDS } from './room/copilot.mjs';
 import { imageStudioFor } from './image-studio.mjs';
 import { CAPABILITIES, imageModuleState } from './capabilities.mjs';
 import { resolveReferences } from './files.mjs';
@@ -134,6 +138,18 @@ export class Room {
   #mother = null;          // MotherChannel: her coded words to the crew
   #shuttingDown = false;
   #inflight = new Set();   // top-level dispatches, from send() and MOTHER, until they settle
+  // Commands an agent asked for, handed back to it once they ran (room/returns.mjs): the ones
+  // waiting for the agent to be free, the ones already handed back, and the ones being handed now.
+  #returns = new Map();    // responseMessageId -> { partial }
+  #returned = new Set();
+  #dropped = new Set();    // stopped by STOP ALL: they go back only when the human hands them back
+  #returning = new Map();  // responseMessageId -> the look in progress, so two never cross
+  #returnCap = new Map();  // responseMessageId -> the highest mode its results may go back at
+  // The copilot (src/room/copilot.mjs): the server's window, the command requests its turns left
+  // to run once the turn has let go of the project, and the rounds run by themselves in a row.
+  #copilotNow = () => null;
+  #copilotRuns = [];
+  #copilotRounds = 0;
   #invokers;
   #agentTimeouts;
   #maxMessageChars;
@@ -175,6 +191,7 @@ export class Room {
     toolsForTurn = null,   // async ({ agent, mode, lease, scratchDir }) => MCP server specs from the modules
     bishopForTurn = null,  // async ({ agent, mode, text, preview, turn }) => bounded BISHOP context in Salas
     linkedForTurn = null,  // async ({ agent, mode, text, preview, turn }) => { text, dynamic } notes a link recalls (3e)
+    copilot = null,        // () => { until } while the human's copilot window is open (src/room/copilot.mjs)
     historicalEvents = [],
     invokers = defaultInvokers,
     agentTimeouts = {},
@@ -215,6 +232,7 @@ export class Room {
     this.#maxConcurrentTurns = maxConcurrentTurns;
     this.#planMaxAgeMs = planMaxAgeMs;
     this.#escalation = new Escalation({ escalationMs });
+    this.#copilotNow = typeof copilot === 'function' ? copilot : () => null;
     this.#controlDesk = controlDesk ?? new ControlDesk({ projectRoot });
     this.#budget = new Budget({ softBudget: softTokenBudget });
     this.#budget.seed(historicalEvents, this.#sentinel);
@@ -276,14 +294,19 @@ export class Room {
   async #askForMode({ planId, plan, step, index, totalSteps, orchestrator, parentMessageId, mode = 2 }) {
     const requestId = randomUUID();
     const expiresAt = new Date(Date.now() + this.#escalation.ms).toISOString();
-    const payload = { requestId, planId, agent: step.agent, orchestrator, mode, step: index + 1, totalSteps, text: step.text, expiresAt, message: `@${step.agent} needs #${mode} ${MODES[mode].label} for step ${index + 1}: the plan runs at #1. Grant it once, for the whole plan, or deny.` };
+    const payload = { requestId, planId, agent: step.agent, orchestrator, mode, step: index + 1, totalSteps, text: step.text, expiresAt, message: `@${step.agent} needs #${mode} ${MODES[mode].label} for step ${index + 1}. Grant it once, for the whole plan, or deny.` };
+    const pending = this.#escalation.wait(requestId, payload, plan);
     await this.#emit('mode.requested', payload);
-    const decision = await this.#escalation.wait(requestId, payload, plan);
+    const decision = await pending;
     if (decision.decision === 'deny' || plan.stopped) {
       const reason = plan.stopped ? 'stopped' : decision.reason ?? 'denied';
-      await this.#emit('mode.denied', { requestId, planId, agent: step.agent, mode, step: index + 1, reason, message: reason === 'timeout' ? `No answer in ${Math.round(this.#escalation.ms / 1000)}s: @${step.agent} runs step ${index + 1} at #1.` : reason === 'stopped' ? `The plan was stopped while @${step.agent} waited for #${mode}.` : `Denied: @${step.agent} runs step ${index + 1} at #1 and will say what it could not create.` });
+      await this.#emit('mode.denied', { requestId, planId, agent: step.agent, mode, step: index + 1, reason, message: reason === 'timeout' ? `No answer in ${Math.round(this.#escalation.ms / 1000)}s: @${step.agent} runs step ${index + 1} at #1.` : reason === 'stopped' ? `The plan was stopped while @${step.agent} waited for #${mode}.` : `Denied: @${step.agent} runs step ${index + 1} at #1 and will say what it could not do.` });
       return { scope: null, reason };
     }
+    if (mode >= 3) {
+      await this.#emit('mode.granted', { requestId, planId, agent: step.agent, mode, step: index + 1, scope: decision.decision, message: `#${mode} granted to @${step.agent}${decision.decision === 'plan' ? ' for the rest of the plan' : ' for this step'}.` });
+      return { scope: decision.decision, mode };
+    }
     const scopes = this.scopesFor(step.agent);
     const enabled = Object.fromEntries(SCOPES.map((scope) => [scope, scopes[scope].enabled && scopes[scope].wired]));
     const lease = await this.#projectLease({ leaseId: randomUUID(), messageId: parentMessageId });
@@ -310,6 +333,7 @@ export class Room {
   // The human's answer to a pending request: 'once', 'plan' or 'deny'.
   decideMode(requestId, decision) { return this.#escalation.decide(requestId, decision); }
   modeAsked(requestId) { return this.#escalation.modeOf(requestId); }
+  modeRequest(requestId) { return this.#escalation.requestOf(requestId); }
   // The modes plans are waiting for the human to grant, as asked.
   pendingModes() { return this.#escalation.pending(); }
 
@@ -718,7 +742,7 @@ export class Room {
   settleDistillation() { return this.#archivist.settle(); }
 
   // Can this message go out at this mode? Answered before the turn exists.
-  async modeCheck({ target, text, mode, create = false } = {}) {
+  async modeCheck({ target, text, mode, create = false, copilot = false } = {}) {
     const parsed = parseMessage(text ?? '', target);
     const wanted = normalizeMode(mode, create === true ? 2 : 1);
     if (!parsed.target) return { ok: true, mode: wanted };
@@ -726,8 +750,10 @@ export class Room {
     const scopes = this.scopesFor(agent);
     if (wanted >= 3) {
       // #3 CONTROL and #4 AIRLOCK: the ceiling must allow it, and there is one holder at a time.
-      // A project without git still checkpoints, in MADRE's shadow repository.
-      if (scopes.maxMode < wanted) return { ok: false, status: 403, mode: wanted, maxMode: scopes.maxMode, error: `@${parsed.target} is capped at #${scopes.maxMode} ${MODES[scopes.maxMode].label}; raise its max mode to #${wanted} in Settings › Permissions to arm ${MODES[wanted].label}.` };
+      // A project without git still checkpoints, in MADRE's shadow repository. The copilot's window
+      // is the human's own #3 for a while: it reaches any agent whose CLI can write.
+      const byCopilot = copilot === true && wanted === 3 && this.copilotOn() && Boolean(scopes.write?.capable);
+      if (scopes.maxMode < wanted && !byCopilot) return { ok: false, status: 403, mode: wanted, maxMode: scopes.maxMode, error: `@${parsed.target} is capped at #${scopes.maxMode} ${MODES[scopes.maxMode].label}; raise its max mode to #${wanted} in Settings › Permissions to unlock ${MODES[wanted].label}.` };
       if (this.#controlDesk.holder) return { ok: false, status: 409, mode: wanted, maxMode: scopes.maxMode, error: `@${this.#controlDesk.holder.agent} already holds ${MODES[this.#controlDesk.holder.mode ?? 3].label} of this project; one holder at a time. STOPALL revokes it.` };
       return { ok: true, mode: wanted, maxMode: scopes.maxMode, agent };
     }
@@ -867,22 +893,26 @@ export class Room {
   // 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.' };
+  async runRequested({ responseMessageId, index, returnCap = 3, auto = false }) {
+    if (!this.#runsEnabled) return { ok: false, status: 412, error: t('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) return { ok: false, status: 404, error: t('That command request is not in this project.') };
     if (!command.argv) return { ok: false, status: 422, error: `That line does not run: it ${whyText(command)}.` };
-    if (this.#runBusy || this.#runDesk.busy) 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.` };
+    if (this.#runBusy || this.#runDesk.busy) return { ok: false, status: 409, error: t('A command is already running; wait for it to finish or press STOP ALL.') };
+    if (this.#controlDesk.holder) return { ok: false, status: 409, error: t('@{agent} is working in {mode} on this project; run it when its turn ends.', { agent: this.#controlDesk.holder.agent, mode: MODES[this.#controlDesk.holder.mode ?? 3].label }) };
+    // A line pressed from a phone hands its results back at #2 at most, the phone's own ceiling.
+    this.#returnCap.set(responseMessageId, Math.min(this.#returnCap.get(responseMessageId) ?? 3, Number(returnCap) || 1));
     // 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; }
+    try { return await this.#runCommand({ request, command, responseMessageId, index, auto }); } finally { this.#runBusy = false; }
   }
 
-  async #runCommand({ request, command, responseMessageId, index }) {
-    const run = { responseMessageId, index, agent: request.agent, line: command.line };
+  async #runCommand({ request, command, responseMessageId, index, auto = false }) {
+    // `auto`: the copilot ran it, nobody pressed it; the card says so.
+    const run = { responseMessageId, index, agent: request.agent, line: command.line, ...(auto ? { auto: 'copilot' } : {}) };
+    const startedAt = Date.now();
     await this.#emit('run.started', run);
     let checkpoint = null;
     try {
@@ -895,6 +925,9 @@ export class Room {
     const finished = this.#runDesk.run({ id: `${responseMessageId}:${index}`, argv: expandHome(command), cwd: this.#projectRoot, onServing: (where) => opened(where) })
       .then(async (result) => {
         const changes = checkpoint ? await this.#controlDesk.changesSince(checkpoint).catch(() => null) : null;
+        // What git cannot see — a folder the project ignores — found by its time on disk.
+        const listed = new Set((changes?.files ?? []).map((file) => file.path));
+        const touched = (await filesChangedSince(this.#projectRoot, startedAt).catch(() => [])).filter((path) => !listed.has(path));
         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',
@@ -902,13 +935,16 @@ export class Room {
           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, served: result.serving ?? undefined, checkpointId: checkpoint?.id, files: changes?.files.length ? changes.files.slice(0, 40) : undefined },
+          run: { ...run, exitCode: result.exitCode, durationMs: result.durationMs, stoppedBy: result.stoppedBy, served: result.serving ?? undefined, checkpointId: checkpoint?.id, files: changes?.files.length ? changes.files.slice(0, 40) : undefined, touched: touched.length ? touched : undefined },
         });
+        // The last line of the request answered: the agent that asked hears how it went.
+        void this.#maybeReturnRun(responseMessageId).catch((error) => console.error(`MADRE could not hand the commands back: ${error.message}`));
         return { ...result, sequence: event.sequence };
       });
     const first = await Promise.race([finished.then((ended) => ({ ended })), serving.then((where) => ({ where }))]);
     if (first.where) {
       await this.#emit('run.serving', { ...run, ...first.where });
+      void this.#maybeReturnRun(responseMessageId).catch((error) => console.error(`MADRE could not hand the commands back: ${error.message}`));
       finished.catch(() => null);
       return { ok: true, status: 200, result: { serving: first.where } };
     }
@@ -920,6 +956,120 @@ export class Room {
     return this.#runDesk.stop('STOP', `${responseMessageId}:${Number(index)}`);
   }
 
+  // Whether the copilot's window is open now: what the server says, nothing kept here.
+  copilotOn() { return Boolean(this.#copilotNow()); }
+
+  // The human ran some of the lines and not the rest, and hands back what there is.
+  returnRun({ responseMessageId, returnCap = 3 } = {}) {
+    const id = String(responseMessageId ?? '');
+    this.#returnCap.set(id, Math.min(this.#returnCap.get(id) ?? 3, Number(returnCap) || 1));
+    return this.#maybeReturnRun(id, { partial: true });
+  }
+
+  // The commands an agent asked for go back to it, once: when every line that can run has an
+  // answer, or when the human hands back what ran. If that agent is still answering, or a plan is
+  // running, it waits for the room to be free (#flushReturns). The turn it starts is the human's —
+  // they pressed the lines — at the mode the asking turn had, never above #3: #4 runs its own
+  // commands and never asks.
+  async #maybeReturnRun(responseMessageId, options = {}) {
+    // One look at a time per request: a line that ends while the human presses «hand back» waits
+    // for the other look instead of being told it was already done.
+    const ahead = this.#returning.get(responseMessageId);
+    const look = (ahead ? ahead.catch(() => null) : Promise.resolve()).then(() => this.#returnRunNow(responseMessageId, options));
+    this.#returning.set(responseMessageId, look);
+    try { return await look; } finally { if (this.#returning.get(responseMessageId) === look) this.#returning.delete(responseMessageId); }
+  }
+
+  async #returnRunNow(responseMessageId, { partial = false } = {}) {
+    if (!responseMessageId || this.#shuttingDown) return { ok: false, status: 409, error: t('MADRE is closing.') };
+    if (this.#returned.has(responseMessageId)) return { ok: false, status: 409, error: t('Those results were already handed back.') };
+    if (partial) this.#dropped.delete(responseMessageId);
+    else if (this.#dropped.has(responseMessageId)) return { ok: false, status: 409, error: t('STOP ALL held these results; hand them back from their card.') };
+    {
+      const events = await this.#store.readAll();
+      if (events.some((event) => event.type === 'message.created' && event.payload?.returns === responseMessageId)) {
+        this.#returned.add(responseMessageId);
+        return { ok: false, status: 409, error: t('Those results were already handed back.') };
+      }
+      const settlement = runSettlement(events, responseMessageId);
+      if (!settlement.request) return { ok: false, status: 404, error: t('That command request is not in this project.') };
+      if (!settlement.ran) return { ok: false, status: 409, error: t('Nothing of that request has run yet.') };
+      if (!settlement.done && !partial) return { ok: true, status: 202, waiting: true };
+      if (this.#runDesk.runningFor(`${responseMessageId}:`)) return { ok: false, status: 409, error: t('A command of that request is still running; wait for it to end.') };
+      const agentId = settlement.request.agent;
+      // STOP ALL may have come while the ledger was read.
+      if (!partial && this.#dropped.has(responseMessageId)) return { ok: false, status: 409, error: t('STOP ALL held these results; hand them back from their card.') };
+      if (this.#plans.size > 0 || [...this.#turns.values()].some((turn) => turn.agent === agentId)) {
+        this.#returns.set(responseMessageId, { partial: partial || Boolean(this.#returns.get(responseMessageId)?.partial) });
+        return { ok: true, status: 202, queued: true };
+      }
+      this.#returns.delete(responseMessageId);
+      this.#returned.add(responseMessageId);
+      const asked = events.find((event) => event.type === 'message.created' && event.payload?.messageId === settlement.request.messageId)?.payload ?? null;
+      const reply = events.find((event) => event.type === 'message.created' && event.payload?.messageId === responseMessageId);
+      const wanted = Math.min(this.#returnCap.get(responseMessageId) ?? 3, Math.max(1, normalizeMode(settlement.request.mode ?? asked?.mode, 1)));
+      // The mode the asking turn had, if the project still allows it and the agent can take it; a
+      // step down otherwise. A CLI that cannot write goes back at #1, not to a refused #2.
+      // A copilot's request goes back under the copilot while the window is open: #3 for any agent
+      // whose CLI writes.
+      const underCopilot = settlement.request.copilot === true && this.copilotOn() && wanted === 3 && Boolean(this.scopesFor(agentId).write?.capable);
+      let mode = underCopilot ? 3 : Math.min(wanted, Math.max(1, this.scopesFor(agentId).maxMode ?? 1));
+      while (mode > 1 && !(await this.modeCheck({ target: agentId, text: '', mode, copilot: underCopilot && mode === 3 })).ok) mode -= 1;
+      const sameAgent = asked?.target === agentId;
+      const quoted = String(settlement.request.reason ?? '').replace(/\s+/g, ' ').trim();
+      const n = settlement.ran;
+      const total = settlement.runnable.length;
+      const said = settlement.done
+        ? n === 1 ? t('The command you asked for ran. Go on with what you proposed.') : t('The {n} commands you asked for ran. Go on with what you proposed.', { n })
+        : t('{n} of the {total} commands you asked for ran. Go on with what you proposed.', { n, total });
+      const text = `↩ @${agentId}${reply?.sequence ? ` #${reply.sequence}` : ''}: “${quoted.length > 120 ? `${quoted.slice(0, 119)}…` : quoted}”\n${said}`;
+      const returned = returnedBlock({ settlement, asking: asked?.text ?? null, said: reply?.payload?.text ?? null, replySequence: reply?.sequence ?? null });
+      await this.#accept({
+        text, target: agentId, mode,
+        model: sameAgent ? asked?.model ?? null : null,
+        effort: sameAgent ? asked?.effort ?? null : null,
+        ash: Boolean(asked?.ash?.requested),
+        followUp: { kind: 'runs', returns: responseMessageId, block: returned },
+        copilot: underCopilot && mode === 3,
+      }, null);
+      return { ok: true, status: 200, returned: true, mode };
+    }
+  }
+
+  // The safe lines a copilot turn asked for, run one after another once that turn let go of the
+  // project; the rest of a request waits for the human, as always. Bounded: after a run of rounds
+  // nobody typed between, the room stops and says so instead of looping on a bill.
+  async #flushCopilotRuns() {
+    while (this.#copilotRuns.length && !this.#shuttingDown) {
+      const responseMessageId = this.#copilotRuns.shift();
+      if (!this.copilotOn() || this.#controlDesk.holder) return;
+      if (this.#copilotRounds >= COPILOT_MAX_ROUNDS) {
+        await this.#alert('copilot-rounds', `The copilot ran commands by itself ${COPILOT_MAX_ROUNDS} times in a row; the next ones wait for you. Write to it to go on.`, `copilot-rounds:${responseMessageId}`);
+        return;
+      }
+      const request = (await this.#store.readAll()).find((event) => event.type === 'run.requested' && event.payload?.responseMessageId === responseMessageId)?.payload;
+      const lines = (request?.commands ?? []).map((command, index) => ({ command, index })).filter(({ command }) => command?.argv && copilotSafe(command.argv));
+      if (!lines.length) continue;
+      this.#copilotRounds += 1;
+      for (const { index } of lines) {
+        if (!this.copilotOn()) return;
+        const ran = await this.runRequested({ responseMessageId, index, returnCap: 3, auto: true });
+        // A line that failed to start or ended badly is still an answer: the next one runs, and
+        // the agent reads both when the request goes back.
+        if (!ran.ok && ran.status === 409) return;
+      }
+    }
+  }
+
+  // What waited for the room to be free goes now, oldest first, one at a time.
+  #flushReturns() {
+    if (!this.#returns.size || this.#shuttingDown || this.#plans.size > 0) return;
+    for (const [responseMessageId, { partial }] of this.#returns) {
+      void this.#track(this.#maybeReturnRun(responseMessageId, { partial })).catch((error) => console.error(`MADRE could not hand the commands back: ${error.message}`));
+      return;
+    }
+  }
+
   ashEnabled() {
     return this.#ashEnabled;
   }
@@ -1021,7 +1171,7 @@ export class Room {
     return { messageId: accepted?.messageId ?? null, responseMessageId: accepted?.responseMessageId ?? null, text: reply?.text ?? null, error: reply ? null : failed?.error ?? 'The turn ended without a reply.' };
   }
 
-  async #accept({ text, target, model = null, effort = null, attachments = [], create = false, ash = false, mode = undefined, draft = false, via = null }, order) {
+  async #accept({ text, target, model = null, effort = null, attachments = [], create = false, ash = false, mode = undefined, draft = false, via = null, followUp = null, copilot = false }, order) {
     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() —
@@ -1031,8 +1181,13 @@ export class Room {
     // A message that came from a phone never goes above #2, whatever reached this far (TEL-01): the
     // bridge and the route say so first; the room says it last, for any road added later.
     if (via && requestedMode > PHONE_MAX_MODE) throw new Error('#3 EDIT and #4 FULL ACCESS are opened from the Mac.');
-    const gate = await this.modeCheck({ target, text, mode: requestedMode });
+    // A copilot message: #3, from this computer, while the window is open. Anything else is a message
+    // like any other, at the mode it was sent with.
+    const asCopilot = copilot === true && requestedMode === 3 && !via && !order && this.copilotOn();
+    const gate = await this.modeCheck({ target, text, mode: requestedMode, copilot: asCopilot });
     if (!gate.ok) throw new Error(gate.error);
+    // Rounds a copilot ran by itself count from the last thing the human wrote.
+    if (!followUp) this.#copilotRounds = 0;
     create = requestedMode === 2;
     const ghost = requestedMode === 0;
     const control = requestedMode >= 3;
@@ -1085,6 +1240,10 @@ export class Room {
       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,
+      // Written by MADRE on the human's behalf: the results of commands an agent asked for.
+      auto: followUp?.kind ?? undefined,
+      returns: followUp?.returns ?? undefined,
+      copilot: asCopilot || undefined,
     });
     // The human may say what they like; the room only says so, because every agent will read it.
     const exposed = this.#privacy?.hits(text2) ?? 0;
@@ -1152,7 +1311,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}`);
     }
-    const responseMessageId = await this.#track(this.#dispatch({ messageId, targetId: parsed.target, text: text2, requester: 'you', depth: order ? order.depth : 0, allowDelegation: allowDelegation && !ghost, model: chosenModel, effort: chosenEffort, attachments: files, references, lease, ash: ashActive, mode: ghost ? 0 : control ? requestedMode : (lease ? 2 : 1) }));
+    const responseMessageId = await this.#track(this.#dispatch({ messageId, targetId: parsed.target, text: text2, requester: 'you', depth: order ? order.depth : 0, allowDelegation: allowDelegation && !ghost, model: chosenModel, effort: chosenEffort, attachments: files, references, lease, ash: ashActive, mode: ghost ? 0 : control ? requestedMode : (lease ? 2 : 1), returned: followUp?.block ?? null, copilot: asCopilot }));
     return { messageId, responseMessageId };
   }
 
@@ -1247,6 +1406,9 @@ export class Room {
     const turns = this.#turns.size;
     for (const plan of this.#plans.values()) plan.stopped = reason;
     this.#escalation.settleAll(null, 'stopped');
+    // Results waiting to go back stay with the human: STOP ALL means nothing starts by itself.
+    for (const id of [...this.#returns.keys(), ...this.#returning.keys()]) this.#dropped.add(id);
+    this.#returns.clear();
     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))] });
@@ -1298,14 +1460,14 @@ 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, effort = null, attachments = [], references = [], lease = null, ash = false, mode = 1, escalation = null }) {
+  async #dispatch({ messageId, targetId, text, requester, depth, planId = null, allowDelegation = true, deferPlan = false, model = null, effort = null, attachments = [], references = [], lease = null, ash = false, mode = 1, escalation = null, returned = null, copilot = false }) {
     if (this.#shuttingDown) return null;
     const agent = this.#agents.find((item) => item.id === targetId);
     if (!agent?.detected) {
       // @madre is not a CLI to install: it is the room's local agent, here while Ollama runs with a
       // chat model. Saying "not installed" sent people to install something that does not exist.
       const error = agent?.local || targetId === 'madre'
-        ? `@${targetId} left the room: Ollama is not running. Start Ollama, or open Ollama in Modules.`
+        ? `@${targetId} left the project: Ollama is not running. Start Ollama, or open Local AI in Modules.`
         : `${targetId} is not installed on this computer.`;
       await this.#emit('message.failed', { messageId, target: targetId, planId, error });
       return null;
@@ -1362,7 +1524,7 @@ export class Room {
     await this.#emit('agent.started', { messageId, agent: agent.id, handoffId, planId, timeoutMs: this.timeoutFor(agent.id, { writing: Number(mode) >= 2 || Boolean(lease) }) });
     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, effort, 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, returned, copilot });
     this.#turns.set(messageId, turn);
     let outcome = null;
     try {
@@ -1370,11 +1532,25 @@ export class Room {
     } finally {
       this.#turns.delete(messageId);
       if (!this.#turns.size && mode !== 0) this.#archivist.schedule();
+      // What a copilot turn asked to run, now that it has let go of the project.
+      void this.#track(this.#flushCopilotRuns()).catch((error) => console.error(`MADRE copilot could not run: ${error.message}`));
+      this.#flushReturns();
     }
     // The orchestrator's turn is over before its plan starts, so it is never
     // counted as in flight while the others work.
-    if (outcome?.directives?.steps.length) {
-      await this.#runPlan({ orchestrator: agent.id, parentMessageId: outcome.responseMessageId, directives: outcome.directives, lease, ash, mode });
+    if (outcome?.directives?.steps.length && !deferPlan) {
+      let next = outcome.directives;
+      let parent = outcome.responseMessageId;
+      const grants = new Map();
+      // The orchestrator may form another wave after seeing the crew's replies. Three waves
+      // bound cost and time; a grant for the plan carries forward, only for its authorized scope.
+      for (let round = 0; next?.steps.length && round < 3; round += 1) {
+        const continued = await this.#runPlan({ orchestrator: agent.id, parentMessageId: parent, directives: next, lease, ash, mode, grants, copilot: copilot && this.copilotOn() });
+        next = continued?.directives ?? null;
+        parent = continued?.responseMessageId ?? parent;
+        lease = continued?.lease ?? lease;
+      }
+      if (next?.steps.length) await this.#emit('plan.ignored', { orchestrator: agent.id, responseMessageId: parent, reasons: ['The plan reached its three-round limit. Continue with a new message if needed.'] });
     }
     return outcome?.responseMessageId ?? null;
   }
@@ -1520,7 +1696,7 @@ export class Room {
     });
   }
 
-  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 }) {
+  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, returned = null, copilot = false }) {
     // 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.
@@ -1533,17 +1709,21 @@ export class Room {
     let controlRun = null;
     let createRun = null;
     let responseMessageId = null;
-    if (mode >= 3 && (requester === 'you' || planId) && depth <= 1 && agentScopes.maxMode >= mode && enabled.write) {
+    // The copilot's #3 reaches past an agent's max mode, never past what its CLI can write.
+    const asCopilot = copilot === true && mode === 3 && this.copilotOn() && Boolean(agentScopes.write?.capable);
+    if (mode >= 3 && (requester === 'you' || planId) && depth <= 1 && (agentScopes.maxMode >= mode || asCopilot) && (enabled.write || asCopilot)) {
       // CONTROL: the project itself is the writable root, and a checkpoint
       // taken now makes every change of this turn reversible. A plan step gets
       // it when the orchestrator, itself in #3, named #3 for that step.
       if (this.#controlDesk.holder) {
-        await this.#alert('control-busy', `@${this.#controlDesk.holder.agent} still holds CONTROL; @${agent.id} answers read-only this turn.`, `control-busy:${agent.id}`);
+        await this.#alert('control-busy', `@${this.#controlDesk.holder.agent} still holds EDIT; @${agent.id} answers read-only this turn.`, `control-busy:${agent.id}`);
       } else {
         await this.#sayWaitingToWrite({ messageId, agent });
         const seat = await this.#controlDesk.begin({ agent, messageId, enabledScopes: enabled, mode, signal }).catch((error) => (error?.code === 'ABORT_ERR' ? null : Promise.reject(error)));
         if (!seat) { await this.#emit('message.failed', { messageId, target: agent.id, planId, error: `Stopped while waiting for the project: another turn was writing in it.`, stopped: true }); return null; }
         controlRun = seat.run;
+        // A copilot does not delete: what it removes is put back when the turn settles.
+        if (asCopilot) controlRun.noDeletes = true;
         lease = seat.lease;
         await this.#emit('control.started', seat.announcement);
       }
@@ -1608,6 +1788,7 @@ export class Room {
       const invoke = this.#invokers[agent.adapter];
       if (!invoke) throw new Error(`${agent.label} does not have a supported MADRE adapter.`);
       const before = lease && !lease.control && !lease.create ? await snapshot(lease.outDir) : null;
+      const writingSince = Date.now();
       responseMessageId = randomUUID();
       this.#liveTurns.set(responseMessageId, { agent: agent.id, mode: turnMode });
       const notesBefore = this.#memory ? this.#memory.maxMemoryId() : 0;
@@ -1625,7 +1806,7 @@ export class Room {
         : null;
       // 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 && turnMode !== 0, runs: this.#runsEnabled && turnMode !== 0 && turnMode < 4, mode: turnMode, escalation, mcpServers, bishop, linked, 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, bishop, linked, returned, copilot: asCopilot && controlRun ? copilotBrief(this.#copilotNow()) : null, 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, servers: [this.#memoryServer?.name, ...mcpServers.map((server) => server.name)].filter(Boolean) });
       // 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.
@@ -1717,7 +1898,7 @@ export class Room {
       // Only a ```pulse fence is a plan, read the way src/directives.mjs reads it; ```pulse-run,
       // ```pulse-ask and ```pulse-salas are not (S-029 in docs/MACROVERSO.md).
       if (depth > 0 && /```pulse\s*\n/i.test(result.text)) {
-        await this.#alert('nested-delegation', `@${agent.id} tried to open a plan from inside a plan. It was ignored; the sequence stays under @${requester}. STOPALL if the room drifts.`, `nested:${agent.id}`);
+        await this.#alert('nested-delegation', `@${agent.id} tried to open a plan from inside a plan. It was ignored; the sequence stays under @${requester}. STOPALL if the project drifts.`, `nested:${agent.id}`);
       }
       // 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;
@@ -1743,6 +1924,7 @@ export class Room {
         synthetic: result.synthetic || undefined,
         redacted: guarded.hits || undefined,
         mode: turnMode,
+        copilot: asCopilot && controlRun ? true : undefined,
         leaseId: lease?.leaseId,
         artifacts: artifacts.length ? artifacts : undefined,
         delegates: directives.steps.length ? directives.steps.map((step) => step.agent) : undefined,
@@ -1752,7 +1934,10 @@ export class Room {
         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, recommended: asked.recommended ?? undefined, modes: asked.modes ?? undefined });
-      if (requested) await this.#emit('run.requested', { messageId, responseMessageId, agent: agent.id, reason: requested.reason, commands: requested.commands });
+      if (requested) {
+        await this.#emit('run.requested', { messageId, responseMessageId, agent: agent.id, reason: requested.reason, commands: requested.commands, mode: turnMode, copilot: asCopilot && controlRun ? true : undefined });
+        if (asCopilot && controlRun) this.#copilotRuns.push(responseMessageId);
+      }
       if (guarded.hits) await this.#emit('privacy.redacted', { agent: agent.id, messageId, responseMessageId, hits: guarded.hits, kinds: guarded.kinds, 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 });
@@ -1773,6 +1958,12 @@ export class Room {
         }
       }
       if (controlChanges) await this.#emit('control.changed', { ...controlChanges, responseMessageId });
+      // A writing turn may also have written where git does not look; the Finder hears about it.
+      if (lease && turnMode >= 2) {
+        const listed = new Set([...artifacts.map((file) => file.path), ...(controlChanges?.files ?? []).map((file) => file.path)]);
+        const touched = (await filesChangedSince(this.#projectRoot, writingSince).catch(() => [])).filter((path) => !listed.has(path));
+        if (touched.length) await this.#emit('files.touched', { agent: agent.id, messageId, responseMessageId, files: touched });
+      }
       // Codex and OpenCode give tokens, not dollars: the turn is priced at the list price of the
       // model it ran on (src/prices.mjs), an estimate that says it is one. Gemini prices itself in
       // its adapter, where its report names each model it used.
@@ -1828,30 +2019,42 @@ export class Room {
     }
   }
 
-  async #runPlan({ orchestrator, parentMessageId, directives, lease = null, ash = false, mode = 1 }) {
+  async #runPlan({ orchestrator, parentMessageId, directives, lease = null, ash = false, mode = 1, grants = new Map(), copilot = false }) {
     const planId = randomUUID();
+    const closing = directives.closing ?? 'Review the delegated answers and the work completed. If more work is needed within the permission already granted by the human, finish your reply with one new pulse plan. If a command requested from the human has not run, say what is waiting. Ask the human only for a decision or a new #3/#4 key.';
     // The plan's ceiling is the human's mode: #3 when the orchestrator held CONTROL, #2 while a
     // lease exists, #1 otherwise. A step may ask for a mode ("@codex #2: …"); it gets the lowest
-    // of what it asked, the ceiling and its own MAX MODE. Without a number it inherits the plan.
+    // of what it asked, the ceiling and its own MAX MODE. Without a number it reads, or creates
+    // while a lease exists: as in 1.0, #3 has to be asked for by name.
     const ceiling = mode >= 3 ? mode : lease ? 2 : 1;
+    // A key for one delegate does not authorize every other provider in the plan, and #4 is never
+    // reached through the human's own #4: a delegate gets it only with its own key.
+    const planGrants = grants;
+    const reach = (agent, asked) => Math.max(asked >= 4 ? Math.min(ceiling, 3) : ceiling, planGrants.get(agent) ?? 0);
+    const askedOf = (step) => normalizeMode(step.mode, lease ? 2 : 1);
+    // Under the copilot the plan gives each step up to #3 whatever its agent's max mode, as long as
+    // its CLI can write; #4 stays the human's.
+    const underCopilot = () => copilot === true && this.copilotOn();
+    const capOf = (scopes) => (underCopilot() && scopes.write?.capable ? Math.max(scopes.maxMode, 3) : scopes.maxMode);
     const stepMode = (step) => {
       const scopes = this.scopesFor(step.agent);
-      const asked = normalizeMode(step.mode, lease ? 2 : 1);
-      const granted = Math.min(asked, ceiling, scopes.maxMode);
-      return granted >= 2 && !scopes.write.enabled ? 1 : granted;
+      const asked = askedOf(step);
+      const granted = Math.min(asked, reach(step.agent, asked), capOf(scopes));
+      return granted >= 2 && !(scopes.write.enabled || (underCopilot() && scopes.write?.capable)) ? 1 : granted;
     };
-    const plan = { planId, orchestrator, steps: directives.steps, closing: directives.closing, step: 0, stopped: null, startedAt: Date.now() };
+    const plan = { planId, orchestrator, steps: directives.steps, closing, step: 0, stopped: null, startedAt: Date.now() };
     this.#plans.set(planId, plan);
     await this.#emit('plan.created', {
       planId,
       orchestrator,
       parentMessageId,
       steps: directives.steps.map((step) => ({ ...step, mode: stepMode(step) })),
-      closing: directives.closing,
+      closing,
       ignored: directives.ignored,
       mode: ceiling,
       leaseId: lease?.leaseId ?? null,
     });
+    let continuation = null;
     try {
       for (const [index, step] of directives.steps.entries()) {
         if (plan.stopped) break;
@@ -1864,7 +2067,18 @@ export class Room {
         let stepLease = lease;
         let escalation = null;
         const stepScopes = this.scopesFor(step.agent);
-        const wanted = stepMode(step);
+        let wanted = stepMode(step);
+        const askedMode = askedOf(step);
+        // #3/#4 are never granted by an agent's text alone. The room waits for the human's
+        // existing key, even when a lower-mode plan asked for a stronger delegate.
+        if (askedMode >= 3 && (askedMode > reach(step.agent, askedMode) || askedMode > capOf(stepScopes))) {
+          const outcome = await this.#askForMode({ planId, plan, step, index, totalSteps: directives.steps.length + 1, orchestrator, parentMessageId, mode: askedMode });
+          if (outcome.scope === 'plan') planGrants.set(step.agent, askedMode);
+          if (outcome.scope) wanted = Math.min(askedMode, this.scopesFor(step.agent).maxMode);
+          // Denied or unanswered, the step reads, as the line in the room says.
+          else { escalation = outcome.reason; wanted = 1; }
+          if (plan.stopped) break;
+        }
         // Under a #3 ceiling the orchestrator's word is enough: a #2 step gets its project lease,
         // a #3 step gets CONTROL for its turn. Under #1 a creation step still asks the human.
         if (ceiling >= 3 && !stepLease && wanted === 2) {
@@ -1873,8 +2087,8 @@ export class Room {
           stepLease.scopes = Object.fromEntries(SCOPES.map((scope) => [scope, stepScopes[scope].enabled && stepScopes[scope].wired]));
           await this.#emit('lease.granted', { delegated: true, leaseId: stepLease.leaseId, messageId, agent: step.agent, outDir: '.', scratchDir: stepLease.scratchDir, grantedBy: orchestrator, scopes: SCOPES.filter((scope) => stepLease.scopes[scope]), unavailable: [], planId });
         }
-        if (ceiling < 3 && !lease && !stepScopes.write.always && (wanted >= 2 || looksLikeCreation(step.text)) && stepScopes.maxMode >= 2 && stepScopes.write.enabled) {
-          const outcome = await this.#askForMode({ planId, plan, step, index, totalSteps: directives.steps.length + (directives.closing ? 1 : 0), orchestrator, parentMessageId, mode: 2 });
+        if (ceiling < 3 && !lease && !stepScopes.write.always && askedMode < 3 && (askedMode >= 2 || looksLikeCreation(step.text)) && stepScopes.maxMode >= 2 && stepScopes.write.enabled) {
+          const outcome = await this.#askForMode({ planId, plan, step, index, totalSteps: directives.steps.length + 1, orchestrator, parentMessageId, mode: 2 });
           if (outcome.scope === 'plan') lease = outcome.lease;
           if (outcome.scope) stepLease = outcome.lease; else escalation = outcome.reason;
           if (plan.stopped) break;
@@ -1891,20 +2105,21 @@ export class Room {
           mode: wanted >= 3 ? wanted : stepLease && stepScopes.write.enabled ? 2 : 1,
           escalation: escalation ?? undefined,
           step: index + 1,
-          totalSteps: directives.steps.length + (directives.closing ? 1 : 0),
+          totalSteps: directives.steps.length + 1,
         });
-        await this.#dispatch({ messageId, targetId: step.agent, text: stepText, requester: orchestrator, depth: 1, planId, allowDelegation: false, lease: wanted >= 3 ? null : stepLease, ash, mode: wanted >= 3 ? wanted : stepLease && stepScopes.write.enabled ? 2 : 1, escalation });
+        await this.#dispatch({ messageId, targetId: step.agent, text: stepText, requester: orchestrator, depth: 1, planId, allowDelegation: false, lease: wanted >= 3 ? null : stepLease, ash, mode: wanted >= 3 ? wanted : stepLease && stepScopes.write.enabled ? 2 : 1, escalation, copilot: wanted === 3 && underCopilot() });
       }
-      if (!plan.stopped && directives.closing) {
+      if (!plan.stopped) {
         plan.step = directives.steps.length + 1;
         const messageId = randomUUID();
+        // A delegate's newly granted #3/#4 never raises the orchestrator's own mode.
         const closingMode = ceiling >= 3 ? ceiling : lease ? 2 : 1;
         await this.#emit('message.created', {
           messageId,
           role: 'assistant',
           sender: orchestrator,
           target: orchestrator,
-          text: directives.closing,
+          text: closing,
           ash: ash ? { active: true } : undefined,
           mode: closingMode,
           status: 'delegated',
@@ -1912,7 +2127,10 @@ export class Room {
           step: plan.step,
           totalSteps: plan.step,
         });
-        await this.#dispatch({ messageId, targetId: orchestrator, text: `${directives.closing}\n(The delegated agents have answered above; this is your closing turn.)`, requester: orchestrator, depth: 1, planId, allowDelegation: false, lease, ash, mode: closingMode });
+        const responseMessageId = await this.#dispatch({ messageId, targetId: orchestrator, text: `${closing}\n(The delegated agents have answered above; this is your closing turn.)`, requester: orchestrator, depth: 0, planId, allowDelegation: true, deferPlan: true, lease, ash, mode: closingMode });
+        const reply = responseMessageId ? (await this.#store.readAll()).find((event) => event.type === 'message.created' && event.payload?.messageId === responseMessageId)?.payload?.text : null;
+        const parsed = reply ? parseDirectives(reply, { self: orchestrator, available: this.delegatesFor(orchestrator), maxSteps: this.#maxPlanSteps }) : null;
+        if (parsed?.steps.length && JSON.stringify(parsed.steps) !== JSON.stringify(directives.steps)) continuation = { responseMessageId, directives: parsed, lease };
       }
     } finally {
       this.#plans.delete(planId);
@@ -1923,5 +2141,6 @@ export class Room {
         reason: plan.stopped ?? null,
       });
     }
+    return continuation;
   }
 }

package/src/router.mjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// MADRE · © 2026 Jossue Alcalá · GNU AGPL v3 with additional terms (Section 7): ADDITIONAL-TERMS.md
 const supported = new Set(['codex', 'claude', 'gemini', 'opencode']);
 
 export function parseMessage(text, fallbackTarget = null) {