@mindstudio-ai/remy 0.1.260 → 0.1.261

package/README.md

@@ -264,6 +264,7 @@ The headless IPC protocol uses request correlation and a unified response patter
 - Every stdout response to a command includes the same `requestId`
 - System events (lifecycle, shutdown) never have a `requestId`
 - Every command ends with exactly one `completed` event: `{event:"completed", requestId, success, error?}`
+- Messages sent while a turn is running are queued. When the turn ends, all contiguous queued user messages and background results are delivered together as **one merged turn**: the first queued message's `requestId` becomes the turn's primary id (stamped on `turn_started` and all streaming events), each absorbed message echoes its own `user_message` with its original `requestId` and `queued: true`, and at turn end the primary `completed` is emitted first, followed immediately by one `completed {…same outcome, absorbed: true}` per other absorbed `requestId`. Automated-action (`@@automated::…@@`) messages and chain steps never merge — they always run one turn each.
 - The caller distinguishes command responses from system events with a single check: `if (msg.requestId)`
 
 This enables a simple promise-based RPC layer: send a command with a unique ID, store a pending promise keyed by that ID, resolve it when you see `completed` with the matching ID.
@@ -364,6 +365,7 @@ All command responses include the `requestId` from the originating command.
 |-------|--------|-------------|
 | `text` | `text`, `parentToolId?` | Streaming text chunk |
 | `thinking` | `text`, `parentToolId?` | Agent's internal reasoning |
+| `user_message` | `text`, `attachments?`, `queued?` | Echo of a user message entering the turn. Queue-delivered messages carry `queued: true` and their own original `requestId` (a merged turn emits one per absorbed message); idle sends echo with the turn's requestId and no `queued` flag. |
 | `tool_start` | `id`, `name`, `input`, `partial?`, `parentToolId?` | Tool execution started. `partial: true` means more `tool_start` events will follow for this id (progressive input streaming). |
 | `tool_input_delta` | `id`, `name`, `result`, `parentToolId?` | Progressive tool content (streaming tools only) |
 | `tool_done` | `id`, `name`, `result`, `isError`, `parentToolId?` | Tool execution completed |
@@ -372,7 +374,7 @@ All command responses include the `requestId` from the originating command.
 | `history` | `messages` | Response to `get_history` |
 | `session_cleared` | | Response to `clear` |
 | `models_changed` | `models?`, `modelSurfaces`, `allowedModelsByType` | Response to `changeModels` |
-| `completed` | `success`, `error?` | Terminal event — exactly one per command |
+| `completed` | `success`, `error?`, `absorbed?` | Terminal event — exactly one per command. For a merged turn, the primary requestId's `completed` comes first, then one `{absorbed: true}` completed per other absorbed requestId with the same outcome — consumers should resolve their pending request but skip turn-lifecycle handling for absorbed terminals. |
 
 #### Example Session
 

package/dist/headless.d.ts

@@ -11,6 +11,10 @@
  * - System events (ready, session_restored, stopping, stopped) never have a requestId.
  * - Every command ends with exactly one `completed` event:
  *   {event:"completed", requestId, success:true|false, error?:string}
+ * - When contiguous queued user/background messages merge into one turn, the
+ *   turn's primary requestId gets the real `completed` first, then each other
+ *   absorbed requestId gets one `{...same outcome, absorbed:true}` completed
+ *   immediately after — one terminal per command either way.
  * - `tool_result` is fire-and-forget (resolves an in-flight promise, no completed event).
  *
  * `get_history` is paginated. Request: {action:"get_history", before?:number,
@@ -46,8 +50,12 @@ declare class HeadlessSession {
     private currentAbort;
     /** RequestId of the in-flight message command — injected into streamed events. */
     private currentRequestId;
-    /** Guard: track whether terminal `completed` was already sent so we emit exactly one. */
+    /** Guard: track whether terminal `completed` was already sent so we emit
+     * exactly one per requestId. */
     private completedEmitted;
+    /** Outcome of the current turn's primary `completed` — read after the turn
+     * to stamp the same success/error onto absorbed requestIds' terminals. */
+    private lastCompleted;
     private turnStart;
     /**
      * Onboarding state of the currently-running turn. Captured at runSingleTurn
@@ -74,6 +82,9 @@ declare class HeadlessSession {
     /** Emit a `completed` event and mark completedEmitted. Queue state is
      * surfaced separately via the `queue_changed` event, not on `completed`. */
     private emitCompleted;
+    /** Outcome of the turn's primary `completed`, for stamping onto absorbed
+     * requestIds' terminals. Falls back to failure if none was emitted. */
+    private primaryOutcome;
     /** Dispatch a simple (non-streaming) command: call handler, emit response + completed. */
     private dispatchSimple;
     /** Persist sessionStats + queue snapshot to .remy-stats.json. */
@@ -98,20 +109,65 @@ declare class HeadlessSession {
     private resolveExternalTool;
     private onEvent;
     /**
-     * Run one turn (without acquiring the `running` lock). Called by
-     * handleMessage for the initial turn, then repeatedly for each queued
-     * message — `running` stays held across the queue drain so no user
-     * message can slip in mid-pipeline.
+     * Persist one entry's non-voice uploads to disk and build its header. The
+     * header tells the LLM where to read each file; it's kept separate so it
+     * gets injected at API-send time and never persisted into the user's chat
+     * content (which would leak into history restore on the frontend).
+     *
+     * Must be awaited sequentially across entries — persistAttachments'
+     * filename de-dup set is per-call, so parallel calls race on names.
+     */
+    private persistEntryAttachments;
+    /**
+     * Run one turn for a single command (without acquiring the `running` lock).
+     * Owns the per-command machinery: @@automated:: action resolution, plan-file
+     * and buildModel side effects, and chain expansion — which is why
+     * sentinel-bearing commands always come through here, one turn each, never
+     * merged. The turn itself runs in executeTurn.
      */
     private runSingleTurn;
+    /**
+     * Run a mailbox batch — contiguous queued user + background items — as one
+     * merged turn. Every item becomes its own history entry and user_message
+     * event (own requestId, attachments, hidden flag); adjacent background
+     * items fold into a single background_results entry so the LLM sees one
+     * combined block. No action-sentinel machinery here: batch construction
+     * guarantees none (sentinel-bearing user items are drain barriers that run
+     * alone via runSingleTurn, and background_results is a NON_ACTION sentinel
+     * with no side effects).
+     */
+    private runMergedTurn;
+    /**
+     * Run one agent turn over the given entries (without acquiring the
+     * `running` lock). Owns the turn-generic lifecycle: request bookkeeping,
+     * the forced-compaction gate, runTurn error handling, and terminal
+     * `completed` events — the primary requestId's completed first, then one
+     * `{absorbed: true}` completed per other absorbed requestId with the same
+     * outcome, on every exit path (done, cancel, error, unexpected), so every
+     * queued message's caller resolves.
+     */
+    private executeTurn;
     private handleMessage;
+    /**
+     * True for queued user items whose text is an @@automated:: action message.
+     * These key per-item raw-text side effects in runSingleTurn (resolveAction,
+     * plan file, buildModel, chain expansion) — they always run alone, one turn
+     * each. Background items are sentinel-formatted too but background_results
+     * is NON_ACTION and side-effect-free, so they merge freely.
+     */
+    private isDrainBarrier;
     /**
      * Drain the queue in strict FIFO order. Caller must hold `running = true`.
      * User messages arriving during the drain will be enqueued behind current items.
      *
-     * Consecutive background-source items are coalesced into a single turn so
-     * the LLM sees all the background results together and produces one
-     * acknowledgment, not N separate ones.
+     * The queue serves two purposes with opposite delivery semantics:
+     * - Sequencer: chain steps and sentinel-bearing user items are pipeline
+     *   stages — one item, one turn, nothing merged in.
+     * - Mailbox: plain user messages and background results are accumulated
+     *   context and intent — everything contiguous flushes together into ONE
+     *   merged turn, so the model reconciles all of it at once instead of
+     *   burning a full turn per item (and possibly executing instructions a
+     *   later queued message already amended).
      */
     private drainQueueLoop;
     /**
@@ -136,9 +192,14 @@ declare class HeadlessSession {
      * Cancel the running turn and flush the follow-ups that belonged to it
      * (`chain`/`background`), while preserving `source: 'user'` items — those are
      * independent user intent, not tied to the aborted run. The preserved user
-     * messages run next: `runSingleTurn` swallows the abort, so `handleMessage`
+     * messages run next: `executeTurn` swallows the abort, so `handleMessage`
      * falls through to `drainQueueLoop` with `running` still held. Returns the
      * flushed items (for the cancel command's resume/discard UX).
+     *
+     * Messages already absorbed into the in-flight merged turn are NOT
+     * preserved — they were delivered into the turn that's being cancelled and
+     * each gets a `{cancelled, absorbed:true}` terminal. Only items still
+     * sitting in the queue survive.
      */
     private handleCancel;
     /**

package/dist/headless.js

@@ -7614,9 +7614,7 @@ function createAgentState() {
 async function runTurn(params) {
   const {
     state,
-    userMessage,
-    attachments,
-    attachmentHeader,
+    entries,
     apiConfig,
     system,
     model,
@@ -7625,7 +7623,6 @@ async function runTurn(params) {
     signal,
     onEvent,
     resolveExternalTool,
-    hidden,
     requestId,
     toolRegistry,
     onBackgroundComplete
@@ -7635,45 +7632,54 @@ async function runTurn(params) {
   const baseline = resolveModel("parent", state.models, model);
   const parentModel = buildModelOverride ?? baseline;
   const modelOverride = buildModelOverride && buildModelOverride !== baseline ? { from: baseline } : void 0;
+  const totalAttachments = entries.reduce(
+    (n, e) => n + (e.attachments?.length ?? 0),
+    0
+  );
   log14.info("Turn started", {
     requestId,
     model,
     buildModel: buildModelOverride,
     toolCount: tools2.length,
-    ...attachments && attachments.length > 0 && {
-      attachmentCount: attachments.length
-    }
+    ...entries.length > 1 && { entryCount: entries.length },
+    ...totalAttachments > 0 && { attachmentCount: totalAttachments }
   });
   onEvent({
     type: "turn_started",
     model: parentModel,
     ...modelOverride && { modelOverride }
   });
-  const hasText = userMessage.trim().length > 0;
-  const hasAttachments = attachments && attachments.length > 0;
-  if (!hasText && !hasAttachments) {
+  const keptEntries = entries.filter(
+    (e) => e.text.trim().length > 0 || (e.attachments?.length ?? 0) > 0
+  );
+  if (keptEntries.length === 0) {
     onEvent({ type: "error", error: "Empty message" });
     return;
   }
-  const userMsg = { role: "user", content: userMessage };
-  if (hidden) {
-    userMsg.hidden = true;
-  }
-  if (hasAttachments) {
-    userMsg.attachments = attachments;
-  }
-  if (attachmentHeader) {
-    userMsg.attachmentHeader = attachmentHeader;
+  for (const entry of keptEntries) {
+    const hasAttachments = (entry.attachments?.length ?? 0) > 0;
+    const userMsg = { role: "user", content: entry.text };
+    if (entry.hidden) {
+      userMsg.hidden = true;
+    }
+    if (hasAttachments) {
+      userMsg.attachments = entry.attachments;
+    }
+    if (entry.attachmentHeader) {
+      userMsg.attachmentHeader = entry.attachmentHeader;
+    }
+    state.messages.push(userMsg);
+    onEvent({
+      type: "user_message",
+      text: entry.text,
+      hidden: entry.hidden || void 0,
+      // Include attachments so the live event can render a queued voice/image/file
+      // bubble; a voice message has empty text and the transcript lives here.
+      ...hasAttachments && { attachments: entry.attachments },
+      ...entry.requestId && { requestId: entry.requestId },
+      ...entry.queued && { queued: true }
+    });
   }
-  state.messages.push(userMsg);
-  onEvent({
-    type: "user_message",
-    text: userMessage,
-    hidden: hidden || void 0,
-    // Include attachments so the live event can render a queued voice/image/file
-    // bubble; a voice message has empty text and the transcript lives here.
-    ...hasAttachments && { attachments }
-  });
   const isFirstMessage = state.messages.filter((m) => m.role === "user").length === 1;
   const STATUS_EXCLUDED_TOOLS = /* @__PURE__ */ new Set([
     "setProjectOnboardingState",
@@ -7742,11 +7748,13 @@ async function runTurn(params) {
         if (onboardingState && onboardingState !== "onboardingFinished") {
           parts.push(`Build phase: ${onboardingState}`);
         }
-        const automated = parseSentinel(userMessage);
-        if (automated) {
-          parts.push(`Automated action: ${automated.name}`);
-        } else if (userMessage) {
-          parts.push(`User request: ${userMessage.slice(-500)}`);
+        for (const entry of keptEntries) {
+          const automated = parseSentinel(entry.text);
+          if (automated) {
+            parts.push(`Automated action: ${automated.name}`);
+          } else if (entry.text) {
+            parts.push(`User request: ${entry.text.slice(-500)}`);
+          }
         }
         return parts.join("\n");
       },
@@ -8291,25 +8299,24 @@ async function persistAttachments(attachments) {
     images: settled.filter((s) => s.isImage).map((s) => s.result)
   };
 }
-function buildUploadHeader(results) {
-  const succeeded = results.filter(Boolean);
-  if (succeeded.length === 0) {
+function buildUploadHeader(documents, images) {
+  const entries = [
+    ...documents.filter((r) => r !== null).map((r) => ({ ...r, isImage: false })),
+    ...images.filter((r) => r !== null).map((r) => ({ ...r, isImage: true }))
+  ];
+  if (entries.length === 0) {
     return "";
   }
-  if (succeeded.length === 1) {
-    const r = succeeded[0];
-    const parts = [`[Uploaded file: ${r.localPath}`];
-    if (r.extractedTextPath) {
-      parts.push(`extracted text: ${r.extractedTextPath}`);
-    }
-    return parts.join(" \u2014 ") + "]";
+  const detail = (e) => e.extractedTextPath ? `extracted text: ${e.extractedTextPath}` : e.isImage ? null : "no extracted text \u2014 raw file only";
+  if (entries.length === 1) {
+    const e = entries[0];
+    const extra = detail(e);
+    return `[Uploaded file: ${e.localPath}${extra ? ` \u2014 ${extra}` : ""}]`;
   }
-  const lines = succeeded.map((r) => {
-    const parts = [`- ${r.localPath}`];
-    if (r.extractedTextPath) {
-      parts.push(`  extracted text: ${r.extractedTextPath}`);
-    }
-    return parts.join("\n");
+  const lines = entries.map((e) => {
+    const extra = detail(e);
+    return `- ${e.localPath}${extra ? `
+  ${extra}` : ""}`;
   });
   return `[Uploaded files]
 ${lines.join("\n")}`;
@@ -8395,6 +8402,17 @@ var MessageQueue = class {
     }
     return item;
   }
+  /** Remove and return the first `n` items; fires onChange once. */
+  shiftMany(n) {
+    if (n <= 0) {
+      return [];
+    }
+    const items = this.items.splice(0, n);
+    if (items.length > 0) {
+      this.onChange?.();
+    }
+    return items;
+  }
   /** Remove and return all queued items. */
   drain() {
     if (this.items.length === 0) {
@@ -8430,6 +8448,10 @@ var MessageQueue = class {
   peek() {
     return this.items[0];
   }
+  /** Return the item at index `i` without removing it. */
+  peekAt(i) {
+    return this.items[i];
+  }
   get length() {
     return this.items.length;
   }
@@ -8512,8 +8534,12 @@ var HeadlessSession = class {
   currentAbort = null;
   /** RequestId of the in-flight message command — injected into streamed events. */
   currentRequestId;
-  /** Guard: track whether terminal `completed` was already sent so we emit exactly one. */
+  /** Guard: track whether terminal `completed` was already sent so we emit
+   * exactly one per requestId. */
   completedEmitted = false;
+  /** Outcome of the current turn's primary `completed` — read after the turn
+   * to stamp the same success/error onto absorbed requestIds' terminals. */
+  lastCompleted = null;
   turnStart = 0;
   /**
    * Onboarding state of the currently-running turn. Captured at runSingleTurn
@@ -8649,6 +8675,15 @@ var HeadlessSession = class {
   emitCompleted(rid, data) {
     this.emit("completed", { ...data }, rid);
     this.completedEmitted = true;
+    this.lastCompleted = {
+      success: data.success === true,
+      ...typeof data.error === "string" && { error: data.error }
+    };
+  }
+  /** Outcome of the turn's primary `completed`, for stamping onto absorbed
+   * requestIds' terminals. Falls back to failure if none was emitted. */
+  primaryOutcome() {
+    return this.lastCompleted ?? { success: false };
   }
   /** Dispatch a simple (non-streaming) command: call handler, emit response + completed. */
   dispatchSimple(requestId, eventName, handler) {
@@ -8807,9 +8842,14 @@ var HeadlessSession = class {
             text: e.text,
             // Forward attachments so queued voice/image/file sends render live;
             // otherwise the bubble is blank until a get_history refresh.
-            ...e.attachments && { attachments: e.attachments }
+            ...e.attachments && { attachments: e.attachments },
+            // Queue-delivered entries are flagged so the frontend renders the
+            // echo (idle sends are rendered optimistically instead).
+            ...e.queued && { queued: true }
           },
-          rid
+          // A merged turn emits one user_message per absorbed entry — each
+          // carries its own original requestId, not the turn's.
+          e.requestId ?? rid
         );
         return;
       // Terminal events — translate to `completed`.
@@ -8832,11 +8872,9 @@ var HeadlessSession = class {
           durationMs: Date.now() - this.turnStart
         });
         return;
-      case "turn_cancelled": {
-        this.emit("completed", { success: false, error: "cancelled" }, rid);
-        this.completedEmitted = true;
+      case "turn_cancelled":
+        this.emitCompleted(rid, { success: false, error: "cancelled" });
         return;
-      }
       // Streaming events — forward with requestId
       case "text":
         this.emit(
@@ -8956,17 +8994,34 @@ var HeadlessSession = class {
   // Message command handler (long-running / streaming)
   //////////////////////////////////////////////////////////////////////////////
   /**
-   * Run one turn (without acquiring the `running` lock). Called by
-   * handleMessage for the initial turn, then repeatedly for each queued
-   * message — `running` stays held across the queue drain so no user
-   * message can slip in mid-pipeline.
+   * Persist one entry's non-voice uploads to disk and build its header. The
+   * header tells the LLM where to read each file; it's kept separate so it
+   * gets injected at API-send time and never persisted into the user's chat
+   * content (which would leak into history restore on the frontend).
+   *
+   * Must be awaited sequentially across entries — persistAttachments'
+   * filename de-dup set is per-call, so parallel calls race on names.
    */
-  async runSingleTurn(parsed, requestId, fromChain = false) {
-    this.currentRequestId = requestId;
-    this.currentAbort = new AbortController();
-    this.completedEmitted = false;
-    this.turnStart = Date.now();
-    await this.runForcedCompactionIfNeeded(requestId);
+  async persistEntryAttachments(attachments) {
+    if (!attachments?.some((a) => !a.isVoice)) {
+      return void 0;
+    }
+    try {
+      const { documents, images } = await persistAttachments(attachments);
+      return buildUploadHeader(documents, images) || void 0;
+    } catch (err) {
+      log16.warn("Attachment persistence failed", { error: err.message });
+      return void 0;
+    }
+  }
+  /**
+   * Run one turn for a single command (without acquiring the `running` lock).
+   * Owns the per-command machinery: @@automated:: action resolution, plan-file
+   * and buildModel side effects, and chain expansion — which is why
+   * sentinel-bearing commands always come through here, one turn each, never
+   * merged. The turn itself runs in executeTurn.
+   */
+  async runSingleTurn(parsed, requestId, fromChain = false, queued = false) {
     const attachments = parsed.attachments;
     if (attachments?.length) {
       log16.info("Message has attachments", {
@@ -8975,19 +9030,7 @@ var HeadlessSession = class {
       });
     }
     let userMessage = parsed.text ?? "";
-    let attachmentHeader;
-    if (attachments?.some((a) => !a.isVoice)) {
-      try {
-        const { documents, images } = await persistAttachments(attachments);
-        const all = [...documents, ...images];
-        const header = buildUploadHeader(all);
-        if (header) {
-          attachmentHeader = header;
-        }
-      } catch (err) {
-        log16.warn("Attachment persistence failed", { error: err.message });
-      }
-    }
+    const attachmentHeader = await this.persistEntryAttachments(attachments);
     let resolved = null;
     try {
       resolved = resolveAction(userMessage);
@@ -9024,22 +9067,108 @@ var HeadlessSession = class {
         });
       }
     }
+    await this.executeTurn({
+      entries: [
+        {
+          text: userMessage,
+          attachments,
+          attachmentHeader,
+          hidden: isHidden || void 0,
+          requestId,
+          queued: queued || void 0
+        }
+      ],
+      requestId,
+      absorbedRids: [],
+      onboardingState,
+      system,
+      buildModel
+    });
+  }
+  /**
+   * Run a mailbox batch — contiguous queued user + background items — as one
+   * merged turn. Every item becomes its own history entry and user_message
+   * event (own requestId, attachments, hidden flag); adjacent background
+   * items fold into a single background_results entry so the LLM sees one
+   * combined block. No action-sentinel machinery here: batch construction
+   * guarantees none (sentinel-bearing user items are drain barriers that run
+   * alone via runSingleTurn, and background_results is a NON_ACTION sentinel
+   * with no side effects).
+   */
+  async runMergedTurn(batch) {
+    const primaryRid = batch[0].command.requestId ?? (batch.every((b) => b.source === "background") ? `background-${Date.now()}` : `merged-${Date.now()}`);
+    const absorbedRids = batch.slice(1).map((b) => b.command.requestId).filter((rid) => typeof rid === "string");
+    const entryList = [];
+    for (const item of batch) {
+      const text = item.command.text ?? "";
+      const prev = entryList[entryList.length - 1];
+      if (item.source === "background" && prev?.background) {
+        prev.entry.text = mergeBackgroundResultsMessages([
+          prev.entry.text,
+          text
+        ]);
+        continue;
+      }
+      entryList.push({
+        background: item.source === "background",
+        entry: {
+          text,
+          attachments: item.command.attachments,
+          hidden: !!item.command.hidden || void 0,
+          // Background items carry no requestId — their user_message falls
+          // back to the turn's primary rid on the wire.
+          requestId: item.command.requestId,
+          queued: true
+        }
+      });
+    }
+    const entries = entryList.map((e) => e.entry);
+    for (const entry of entries) {
+      entry.attachmentHeader = await this.persistEntryAttachments(
+        entry.attachments
+      );
+    }
+    const onboardingState = batch.find((b) => b.command.onboardingState !== void 0)?.command.onboardingState ?? this.currentOnboardingState ?? "onboardingFinished";
+    this.currentOnboardingState = onboardingState;
+    const viewContext = [...batch].reverse().find((b) => b.command.viewContext !== void 0)?.command.viewContext;
+    await this.executeTurn({
+      entries,
+      requestId: primaryRid,
+      absorbedRids,
+      onboardingState,
+      system: buildSystemPrompt(onboardingState, viewContext)
+    });
+  }
+  /**
+   * Run one agent turn over the given entries (without acquiring the
+   * `running` lock). Owns the turn-generic lifecycle: request bookkeeping,
+   * the forced-compaction gate, runTurn error handling, and terminal
+   * `completed` events — the primary requestId's completed first, then one
+   * `{absorbed: true}` completed per other absorbed requestId with the same
+   * outcome, on every exit path (done, cancel, error, unexpected), so every
+   * queued message's caller resolves.
+   */
+  async executeTurn(params) {
+    const { entries, requestId, absorbedRids, onboardingState, system } = params;
+    this.currentRequestId = requestId;
+    this.currentAbort = new AbortController();
+    this.completedEmitted = false;
+    this.lastCompleted = null;
+    this.turnStart = Date.now();
+    await this.runForcedCompactionIfNeeded(requestId);
     try {
       await runTurn({
         state: this.state,
-        userMessage,
-        attachments,
-        attachmentHeader,
+        entries,
         apiConfig: this.config,
         system,
         model: this.opts.model,
-        buildModel,
+        buildModel: params.buildModel,
         onboardingState,
         requestId,
         signal: this.currentAbort.signal,
         onEvent: this.onEvent,
         resolveExternalTool: this.resolveExternalTool,
-        hidden: isHidden,
         toolRegistry: this.toolRegistry,
         onBackgroundComplete: this.onBackgroundComplete
       });
@@ -9067,6 +9196,18 @@ var HeadlessSession = class {
         error: err.message
       });
     }
+    const outcome = this.primaryOutcome();
+    for (const rid of absorbedRids) {
+      this.emit(
+        "completed",
+        {
+          success: outcome.success,
+          ...outcome.error && { error: outcome.error },
+          absorbed: true
+        },
+        rid
+      );
+    }
     applyPendingSummaries(this.state);
     this.applyPendingBlockUpdates();
   }
@@ -9093,42 +9234,61 @@ var HeadlessSession = class {
       this.running = false;
     }
   }
+  /**
+   * True for queued user items whose text is an @@automated:: action message.
+   * These key per-item raw-text side effects in runSingleTurn (resolveAction,
+   * plan file, buildModel, chain expansion) — they always run alone, one turn
+   * each. Background items are sentinel-formatted too but background_results
+   * is NON_ACTION and side-effect-free, so they merge freely.
+   */
+  isDrainBarrier(item) {
+    return item.source === "user" && isAutomatedMessage(item.command.text ?? "");
+  }
   /**
    * Drain the queue in strict FIFO order. Caller must hold `running = true`.
    * User messages arriving during the drain will be enqueued behind current items.
    *
-   * Consecutive background-source items are coalesced into a single turn so
-   * the LLM sees all the background results together and produces one
-   * acknowledgment, not N separate ones.
+   * The queue serves two purposes with opposite delivery semantics:
+   * - Sequencer: chain steps and sentinel-bearing user items are pipeline
+   *   stages — one item, one turn, nothing merged in.
+   * - Mailbox: plain user messages and background results are accumulated
+   *   context and intent — everything contiguous flushes together into ONE
+   *   merged turn, so the model reconciles all of it at once instead of
+   *   burning a full turn per item (and possibly executing instructions a
+   *   later queued message already amended).
    */
   async drainQueueLoop() {
-    while (true) {
-      const next = this.queue.shift();
-      if (!next) {
-        break;
+    while (this.queue.length > 0) {
+      const head = this.queue.peek();
+      if (head.source === "chain") {
+        const item = this.queue.shift();
+        const rid = item.command.requestId ?? `chain-${Date.now()}`;
+        await this.runSingleTurn(item.command, rid, true);
+        continue;
       }
-      if (next.source === "background") {
-        const batch = [next];
-        while (this.queue.peek()?.source === "background") {
-          const more = this.queue.shift();
-          if (more) {
-            batch.push(more);
-          }
-        }
-        const combinedCommand = {
-          action: "message",
-          text: mergeBackgroundResultsMessages(
-            batch.map((b) => b.command.text ?? "")
-          ),
-          ...this.currentOnboardingState && {
-            onboardingState: this.currentOnboardingState
-          }
-        };
-        await this.runSingleTurn(combinedCommand, `background-${Date.now()}`);
+      if (this.isDrainBarrier(head)) {
+        const item = this.queue.shift();
+        const rid = item.command.requestId ?? `user-${Date.now()}`;
+        await this.runSingleTurn(item.command, rid, false, true);
         continue;
       }
-      const nextRid = next.command.requestId ?? `${next.source}-${Date.now()}`;
-      await this.runSingleTurn(next.command, nextRid, next.source === "chain");
+      let n = 1;
+      let batchOb = head.command.onboardingState;
+      for (; ; n++) {
+        const it = this.queue.peekAt(n);
+        if (!it || it.source === "chain" || this.isDrainBarrier(it)) {
+          break;
+        }
+        const ob = it.command.onboardingState;
+        if (ob !== void 0 && batchOb !== void 0 && ob !== batchOb) {
+          break;
+        }
+        if (ob !== void 0 && batchOb === void 0) {
+          batchOb = ob;
+        }
+      }
+      const batch = this.queue.shiftMany(n);
+      await this.runMergedTurn(batch);
     }
   }
   /**
@@ -9184,9 +9344,14 @@ var HeadlessSession = class {
    * Cancel the running turn and flush the follow-ups that belonged to it
    * (`chain`/`background`), while preserving `source: 'user'` items — those are
    * independent user intent, not tied to the aborted run. The preserved user
-   * messages run next: `runSingleTurn` swallows the abort, so `handleMessage`
+   * messages run next: `executeTurn` swallows the abort, so `handleMessage`
    * falls through to `drainQueueLoop` with `running` still held. Returns the
    * flushed items (for the cancel command's resume/discard UX).
+   *
+   * Messages already absorbed into the in-flight merged turn are NOT
+   * preserved — they were delivered into the turn that's being cancelled and
+   * each gets a `{cancelled, absorbed:true}` terminal. Only items still
+   * sitting in the queue survive.
    */
   handleCancel() {
     if (this.currentAbort) {

package/dist/index.js

@@ -8091,9 +8091,7 @@ function createAgentState() {
 async function runTurn(params) {
   const {
     state,
-    userMessage,
-    attachments,
-    attachmentHeader,
+    entries,
     apiConfig,
     system,
     model,
@@ -8102,7 +8100,6 @@ async function runTurn(params) {
     signal,
     onEvent,
     resolveExternalTool,
-    hidden,
     requestId,
     toolRegistry,
     onBackgroundComplete
@@ -8112,45 +8109,54 @@ async function runTurn(params) {
   const baseline = resolveModel("parent", state.models, model);
   const parentModel = buildModelOverride ?? baseline;
   const modelOverride = buildModelOverride && buildModelOverride !== baseline ? { from: baseline } : void 0;
+  const totalAttachments = entries.reduce(
+    (n, e) => n + (e.attachments?.length ?? 0),
+    0
+  );
   log13.info("Turn started", {
     requestId,
     model,
     buildModel: buildModelOverride,
     toolCount: tools2.length,
-    ...attachments && attachments.length > 0 && {
-      attachmentCount: attachments.length
-    }
+    ...entries.length > 1 && { entryCount: entries.length },
+    ...totalAttachments > 0 && { attachmentCount: totalAttachments }
   });
   onEvent({
     type: "turn_started",
     model: parentModel,
     ...modelOverride && { modelOverride }
   });
-  const hasText = userMessage.trim().length > 0;
-  const hasAttachments = attachments && attachments.length > 0;
-  if (!hasText && !hasAttachments) {
+  const keptEntries = entries.filter(
+    (e) => e.text.trim().length > 0 || (e.attachments?.length ?? 0) > 0
+  );
+  if (keptEntries.length === 0) {
     onEvent({ type: "error", error: "Empty message" });
     return;
   }
-  const userMsg = { role: "user", content: userMessage };
-  if (hidden) {
-    userMsg.hidden = true;
-  }
-  if (hasAttachments) {
-    userMsg.attachments = attachments;
-  }
-  if (attachmentHeader) {
-    userMsg.attachmentHeader = attachmentHeader;
+  for (const entry of keptEntries) {
+    const hasAttachments = (entry.attachments?.length ?? 0) > 0;
+    const userMsg = { role: "user", content: entry.text };
+    if (entry.hidden) {
+      userMsg.hidden = true;
+    }
+    if (hasAttachments) {
+      userMsg.attachments = entry.attachments;
+    }
+    if (entry.attachmentHeader) {
+      userMsg.attachmentHeader = entry.attachmentHeader;
+    }
+    state.messages.push(userMsg);
+    onEvent({
+      type: "user_message",
+      text: entry.text,
+      hidden: entry.hidden || void 0,
+      // Include attachments so the live event can render a queued voice/image/file
+      // bubble; a voice message has empty text and the transcript lives here.
+      ...hasAttachments && { attachments: entry.attachments },
+      ...entry.requestId && { requestId: entry.requestId },
+      ...entry.queued && { queued: true }
+    });
   }
-  state.messages.push(userMsg);
-  onEvent({
-    type: "user_message",
-    text: userMessage,
-    hidden: hidden || void 0,
-    // Include attachments so the live event can render a queued voice/image/file
-    // bubble; a voice message has empty text and the transcript lives here.
-    ...hasAttachments && { attachments }
-  });
   const isFirstMessage = state.messages.filter((m) => m.role === "user").length === 1;
   const STATUS_EXCLUDED_TOOLS = /* @__PURE__ */ new Set([
     "setProjectOnboardingState",
@@ -8219,11 +8225,13 @@ async function runTurn(params) {
         if (onboardingState && onboardingState !== "onboardingFinished") {
           parts.push(`Build phase: ${onboardingState}`);
         }
-        const automated = parseSentinel(userMessage);
-        if (automated) {
-          parts.push(`Automated action: ${automated.name}`);
-        } else if (userMessage) {
-          parts.push(`User request: ${userMessage.slice(-500)}`);
+        for (const entry of keptEntries) {
+          const automated = parseSentinel(entry.text);
+          if (automated) {
+            parts.push(`Automated action: ${automated.name}`);
+          } else if (entry.text) {
+            parts.push(`User request: ${entry.text.slice(-500)}`);
+          }
         }
         return parts.join("\n");
       },
@@ -9144,25 +9152,24 @@ async function persistAttachments(attachments) {
     images: settled.filter((s) => s.isImage).map((s) => s.result)
   };
 }
-function buildUploadHeader(results) {
-  const succeeded = results.filter(Boolean);
-  if (succeeded.length === 0) {
+function buildUploadHeader(documents, images) {
+  const entries = [
+    ...documents.filter((r) => r !== null).map((r) => ({ ...r, isImage: false })),
+    ...images.filter((r) => r !== null).map((r) => ({ ...r, isImage: true }))
+  ];
+  if (entries.length === 0) {
     return "";
   }
-  if (succeeded.length === 1) {
-    const r = succeeded[0];
-    const parts = [`[Uploaded file: ${r.localPath}`];
-    if (r.extractedTextPath) {
-      parts.push(`extracted text: ${r.extractedTextPath}`);
-    }
-    return parts.join(" \u2014 ") + "]";
+  const detail = (e) => e.extractedTextPath ? `extracted text: ${e.extractedTextPath}` : e.isImage ? null : "no extracted text \u2014 raw file only";
+  if (entries.length === 1) {
+    const e = entries[0];
+    const extra = detail(e);
+    return `[Uploaded file: ${e.localPath}${extra ? ` \u2014 ${extra}` : ""}]`;
   }
-  const lines = succeeded.map((r) => {
-    const parts = [`- ${r.localPath}`];
-    if (r.extractedTextPath) {
-      parts.push(`  extracted text: ${r.extractedTextPath}`);
-    }
-    return parts.join("\n");
+  const lines = entries.map((e) => {
+    const extra = detail(e);
+    return `- ${e.localPath}${extra ? `
+  ${extra}` : ""}`;
   });
   return `[Uploaded files]
 ${lines.join("\n")}`;
@@ -9275,6 +9282,17 @@ var init_messageQueue = __esm({
         }
         return item;
       }
+      /** Remove and return the first `n` items; fires onChange once. */
+      shiftMany(n) {
+        if (n <= 0) {
+          return [];
+        }
+        const items = this.items.splice(0, n);
+        if (items.length > 0) {
+          this.onChange?.();
+        }
+        return items;
+      }
       /** Remove and return all queued items. */
       drain() {
         if (this.items.length === 0) {
@@ -9310,6 +9328,10 @@ var init_messageQueue = __esm({
       peek() {
         return this.items[0];
       }
+      /** Return the item at index `i` without removing it. */
+      peekAt(i) {
+        return this.items[i];
+      }
       get length() {
         return this.items.length;
       }
@@ -9427,8 +9449,12 @@ var init_headless = __esm({
       currentAbort = null;
       /** RequestId of the in-flight message command — injected into streamed events. */
       currentRequestId;
-      /** Guard: track whether terminal `completed` was already sent so we emit exactly one. */
+      /** Guard: track whether terminal `completed` was already sent so we emit
+       * exactly one per requestId. */
       completedEmitted = false;
+      /** Outcome of the current turn's primary `completed` — read after the turn
+       * to stamp the same success/error onto absorbed requestIds' terminals. */
+      lastCompleted = null;
       turnStart = 0;
       /**
        * Onboarding state of the currently-running turn. Captured at runSingleTurn
@@ -9564,6 +9590,15 @@ var init_headless = __esm({
       emitCompleted(rid, data) {
         this.emit("completed", { ...data }, rid);
         this.completedEmitted = true;
+        this.lastCompleted = {
+          success: data.success === true,
+          ...typeof data.error === "string" && { error: data.error }
+        };
+      }
+      /** Outcome of the turn's primary `completed`, for stamping onto absorbed
+       * requestIds' terminals. Falls back to failure if none was emitted. */
+      primaryOutcome() {
+        return this.lastCompleted ?? { success: false };
       }
       /** Dispatch a simple (non-streaming) command: call handler, emit response + completed. */
       dispatchSimple(requestId, eventName, handler) {
@@ -9722,9 +9757,14 @@ var init_headless = __esm({
                 text: e.text,
                 // Forward attachments so queued voice/image/file sends render live;
                 // otherwise the bubble is blank until a get_history refresh.
-                ...e.attachments && { attachments: e.attachments }
+                ...e.attachments && { attachments: e.attachments },
+                // Queue-delivered entries are flagged so the frontend renders the
+                // echo (idle sends are rendered optimistically instead).
+                ...e.queued && { queued: true }
               },
-              rid
+              // A merged turn emits one user_message per absorbed entry — each
+              // carries its own original requestId, not the turn's.
+              e.requestId ?? rid
             );
             return;
           // Terminal events — translate to `completed`.
@@ -9747,11 +9787,9 @@ var init_headless = __esm({
               durationMs: Date.now() - this.turnStart
             });
             return;
-          case "turn_cancelled": {
-            this.emit("completed", { success: false, error: "cancelled" }, rid);
-            this.completedEmitted = true;
+          case "turn_cancelled":
+            this.emitCompleted(rid, { success: false, error: "cancelled" });
             return;
-          }
           // Streaming events — forward with requestId
           case "text":
             this.emit(
@@ -9871,17 +9909,34 @@ var init_headless = __esm({
       // Message command handler (long-running / streaming)
       //////////////////////////////////////////////////////////////////////////////
       /**
-       * Run one turn (without acquiring the `running` lock). Called by
-       * handleMessage for the initial turn, then repeatedly for each queued
-       * message — `running` stays held across the queue drain so no user
-       * message can slip in mid-pipeline.
+       * Persist one entry's non-voice uploads to disk and build its header. The
+       * header tells the LLM where to read each file; it's kept separate so it
+       * gets injected at API-send time and never persisted into the user's chat
+       * content (which would leak into history restore on the frontend).
+       *
+       * Must be awaited sequentially across entries — persistAttachments'
+       * filename de-dup set is per-call, so parallel calls race on names.
        */
-      async runSingleTurn(parsed, requestId, fromChain = false) {
-        this.currentRequestId = requestId;
-        this.currentAbort = new AbortController();
-        this.completedEmitted = false;
-        this.turnStart = Date.now();
-        await this.runForcedCompactionIfNeeded(requestId);
+      async persistEntryAttachments(attachments) {
+        if (!attachments?.some((a) => !a.isVoice)) {
+          return void 0;
+        }
+        try {
+          const { documents, images } = await persistAttachments(attachments);
+          return buildUploadHeader(documents, images) || void 0;
+        } catch (err) {
+          log16.warn("Attachment persistence failed", { error: err.message });
+          return void 0;
+        }
+      }
+      /**
+       * Run one turn for a single command (without acquiring the `running` lock).
+       * Owns the per-command machinery: @@automated:: action resolution, plan-file
+       * and buildModel side effects, and chain expansion — which is why
+       * sentinel-bearing commands always come through here, one turn each, never
+       * merged. The turn itself runs in executeTurn.
+       */
+      async runSingleTurn(parsed, requestId, fromChain = false, queued = false) {
         const attachments = parsed.attachments;
         if (attachments?.length) {
           log16.info("Message has attachments", {
@@ -9890,19 +9945,7 @@ var init_headless = __esm({
           });
         }
         let userMessage = parsed.text ?? "";
-        let attachmentHeader;
-        if (attachments?.some((a) => !a.isVoice)) {
-          try {
-            const { documents, images } = await persistAttachments(attachments);
-            const all = [...documents, ...images];
-            const header = buildUploadHeader(all);
-            if (header) {
-              attachmentHeader = header;
-            }
-          } catch (err) {
-            log16.warn("Attachment persistence failed", { error: err.message });
-          }
-        }
+        const attachmentHeader = await this.persistEntryAttachments(attachments);
         let resolved = null;
         try {
           resolved = resolveAction(userMessage);
@@ -9939,22 +9982,108 @@ var init_headless = __esm({
             });
           }
         }
+        await this.executeTurn({
+          entries: [
+            {
+              text: userMessage,
+              attachments,
+              attachmentHeader,
+              hidden: isHidden || void 0,
+              requestId,
+              queued: queued || void 0
+            }
+          ],
+          requestId,
+          absorbedRids: [],
+          onboardingState,
+          system,
+          buildModel
+        });
+      }
+      /**
+       * Run a mailbox batch — contiguous queued user + background items — as one
+       * merged turn. Every item becomes its own history entry and user_message
+       * event (own requestId, attachments, hidden flag); adjacent background
+       * items fold into a single background_results entry so the LLM sees one
+       * combined block. No action-sentinel machinery here: batch construction
+       * guarantees none (sentinel-bearing user items are drain barriers that run
+       * alone via runSingleTurn, and background_results is a NON_ACTION sentinel
+       * with no side effects).
+       */
+      async runMergedTurn(batch) {
+        const primaryRid = batch[0].command.requestId ?? (batch.every((b) => b.source === "background") ? `background-${Date.now()}` : `merged-${Date.now()}`);
+        const absorbedRids = batch.slice(1).map((b) => b.command.requestId).filter((rid) => typeof rid === "string");
+        const entryList = [];
+        for (const item of batch) {
+          const text = item.command.text ?? "";
+          const prev = entryList[entryList.length - 1];
+          if (item.source === "background" && prev?.background) {
+            prev.entry.text = mergeBackgroundResultsMessages([
+              prev.entry.text,
+              text
+            ]);
+            continue;
+          }
+          entryList.push({
+            background: item.source === "background",
+            entry: {
+              text,
+              attachments: item.command.attachments,
+              hidden: !!item.command.hidden || void 0,
+              // Background items carry no requestId — their user_message falls
+              // back to the turn's primary rid on the wire.
+              requestId: item.command.requestId,
+              queued: true
+            }
+          });
+        }
+        const entries = entryList.map((e) => e.entry);
+        for (const entry of entries) {
+          entry.attachmentHeader = await this.persistEntryAttachments(
+            entry.attachments
+          );
+        }
+        const onboardingState = batch.find((b) => b.command.onboardingState !== void 0)?.command.onboardingState ?? this.currentOnboardingState ?? "onboardingFinished";
+        this.currentOnboardingState = onboardingState;
+        const viewContext = [...batch].reverse().find((b) => b.command.viewContext !== void 0)?.command.viewContext;
+        await this.executeTurn({
+          entries,
+          requestId: primaryRid,
+          absorbedRids,
+          onboardingState,
+          system: buildSystemPrompt(onboardingState, viewContext)
+        });
+      }
+      /**
+       * Run one agent turn over the given entries (without acquiring the
+       * `running` lock). Owns the turn-generic lifecycle: request bookkeeping,
+       * the forced-compaction gate, runTurn error handling, and terminal
+       * `completed` events — the primary requestId's completed first, then one
+       * `{absorbed: true}` completed per other absorbed requestId with the same
+       * outcome, on every exit path (done, cancel, error, unexpected), so every
+       * queued message's caller resolves.
+       */
+      async executeTurn(params) {
+        const { entries, requestId, absorbedRids, onboardingState, system } = params;
+        this.currentRequestId = requestId;
+        this.currentAbort = new AbortController();
+        this.completedEmitted = false;
+        this.lastCompleted = null;
+        this.turnStart = Date.now();
+        await this.runForcedCompactionIfNeeded(requestId);
         try {
           await runTurn({
             state: this.state,
-            userMessage,
-            attachments,
-            attachmentHeader,
+            entries,
             apiConfig: this.config,
             system,
             model: this.opts.model,
-            buildModel,
+            buildModel: params.buildModel,
             onboardingState,
             requestId,
             signal: this.currentAbort.signal,
             onEvent: this.onEvent,
             resolveExternalTool: this.resolveExternalTool,
-            hidden: isHidden,
             toolRegistry: this.toolRegistry,
             onBackgroundComplete: this.onBackgroundComplete
           });
@@ -9982,6 +10111,18 @@ var init_headless = __esm({
             error: err.message
           });
         }
+        const outcome = this.primaryOutcome();
+        for (const rid of absorbedRids) {
+          this.emit(
+            "completed",
+            {
+              success: outcome.success,
+              ...outcome.error && { error: outcome.error },
+              absorbed: true
+            },
+            rid
+          );
+        }
         applyPendingSummaries(this.state);
         this.applyPendingBlockUpdates();
       }
@@ -10008,42 +10149,61 @@ var init_headless = __esm({
           this.running = false;
         }
       }
+      /**
+       * True for queued user items whose text is an @@automated:: action message.
+       * These key per-item raw-text side effects in runSingleTurn (resolveAction,
+       * plan file, buildModel, chain expansion) — they always run alone, one turn
+       * each. Background items are sentinel-formatted too but background_results
+       * is NON_ACTION and side-effect-free, so they merge freely.
+       */
+      isDrainBarrier(item) {
+        return item.source === "user" && isAutomatedMessage(item.command.text ?? "");
+      }
       /**
        * Drain the queue in strict FIFO order. Caller must hold `running = true`.
        * User messages arriving during the drain will be enqueued behind current items.
        *
-       * Consecutive background-source items are coalesced into a single turn so
-       * the LLM sees all the background results together and produces one
-       * acknowledgment, not N separate ones.
+       * The queue serves two purposes with opposite delivery semantics:
+       * - Sequencer: chain steps and sentinel-bearing user items are pipeline
+       *   stages — one item, one turn, nothing merged in.
+       * - Mailbox: plain user messages and background results are accumulated
+       *   context and intent — everything contiguous flushes together into ONE
+       *   merged turn, so the model reconciles all of it at once instead of
+       *   burning a full turn per item (and possibly executing instructions a
+       *   later queued message already amended).
        */
       async drainQueueLoop() {
-        while (true) {
-          const next = this.queue.shift();
-          if (!next) {
-            break;
+        while (this.queue.length > 0) {
+          const head = this.queue.peek();
+          if (head.source === "chain") {
+            const item = this.queue.shift();
+            const rid = item.command.requestId ?? `chain-${Date.now()}`;
+            await this.runSingleTurn(item.command, rid, true);
+            continue;
           }
-          if (next.source === "background") {
-            const batch = [next];
-            while (this.queue.peek()?.source === "background") {
-              const more = this.queue.shift();
-              if (more) {
-                batch.push(more);
-              }
-            }
-            const combinedCommand = {
-              action: "message",
-              text: mergeBackgroundResultsMessages(
-                batch.map((b) => b.command.text ?? "")
-              ),
-              ...this.currentOnboardingState && {
-                onboardingState: this.currentOnboardingState
-              }
-            };
-            await this.runSingleTurn(combinedCommand, `background-${Date.now()}`);
+          if (this.isDrainBarrier(head)) {
+            const item = this.queue.shift();
+            const rid = item.command.requestId ?? `user-${Date.now()}`;
+            await this.runSingleTurn(item.command, rid, false, true);
             continue;
           }
-          const nextRid = next.command.requestId ?? `${next.source}-${Date.now()}`;
-          await this.runSingleTurn(next.command, nextRid, next.source === "chain");
+          let n = 1;
+          let batchOb = head.command.onboardingState;
+          for (; ; n++) {
+            const it = this.queue.peekAt(n);
+            if (!it || it.source === "chain" || this.isDrainBarrier(it)) {
+              break;
+            }
+            const ob = it.command.onboardingState;
+            if (ob !== void 0 && batchOb !== void 0 && ob !== batchOb) {
+              break;
+            }
+            if (ob !== void 0 && batchOb === void 0) {
+              batchOb = ob;
+            }
+          }
+          const batch = this.queue.shiftMany(n);
+          await this.runMergedTurn(batch);
         }
       }
       /**
@@ -10099,9 +10259,14 @@ var init_headless = __esm({
        * Cancel the running turn and flush the follow-ups that belonged to it
        * (`chain`/`background`), while preserving `source: 'user'` items — those are
        * independent user intent, not tied to the aborted run. The preserved user
-       * messages run next: `runSingleTurn` swallows the abort, so `handleMessage`
+       * messages run next: `executeTurn` swallows the abort, so `handleMessage`
        * falls through to `drainQueueLoop` with `running` still held. Returns the
        * flushed items (for the cancel command's resume/discard UX).
+       *
+       * Messages already absorbed into the in-flight merged turn are NOT
+       * preserved — they were delivered into the turn that's being cancelled and
+       * each gets a `{cancelled, absorbed:true}` terminal. Only items still
+       * sitting in the queue survive.
        */
       handleCancel() {
         if (this.currentAbort) {
@@ -10528,7 +10693,7 @@ function App({ apiConfig, model }) {
       try {
         await runTurn({
           state: agentState,
-          userMessage: message,
+          entries: [{ text: message }],
           apiConfig,
           system,
           model,

package/dist/prompt/static/instructions.md

@@ -28,7 +28,7 @@ The user can already see your tool calls, so most of your work is visible withou
 Skip the rest: narrating what you're about to do, restating what the user asked, explaining tool calls they can already see.
 
 ### User attachments
-When a user uploads a file (PDF, Word doc, image, etc.), it is automatically saved to `src/.user-uploads/` in the project directory. The message includes the local file path, and for documents with extractable text, a `.txt` sidecar with the extracted content. Use `readFile` on the sidecar to access document contents. Pass the file path itself to tools that take an image — `screenshot`, and the design expert's `analyzeImage` / `analyzeDesign` / `editImages` — and they host the file and hand back a URL you can reuse or embed in a spec. If a raw file from `src/` needs to be served by the web interface, copy it to `dist/interfaces/web/public/`. These files persist across the conversation — they survive compaction and session restarts. Do not ask the user to re-upload a document that has already been saved. Voice messages are not saved to disk — their transcripts appear inline in the message.
+When a user uploads a file (PDF, Word doc, image, etc.), it is automatically saved to `src/.user-uploads/` in the project directory. The message includes the local file path, and for documents with extractable text, a `.txt` sidecar with the extracted content you can read with `readFile`. A document marked "no extracted text — raw file only" has no sidecar: parse the raw file yourself, and if it is genuinely unreadable, tell the user what happened. Pass the file path itself to tools that take an image — `screenshot`, and the design expert's `analyzeImage` / `analyzeDesign` / `editImages` — and they host the file and hand back a URL you can reuse or embed in a spec. If a raw file from `src/` needs to be served by the web interface, copy it to `dist/interfaces/web/public/`. These files persist across the conversation — they survive compaction and session restarts. Do not ask the user to re-upload a document that has already been saved. Voice messages are not saved to disk — their transcripts appear inline in the message.
 
 ### Automated messages
 You will occasionally receive automated messages prefixed with `@@automated_message@@` - these are triggered by things like background agents returning their work, or by the user clicking a button in the UI (e.g., the user might click a "Build Feature" button in the product roadmap UI, and you will receive a message detailing what they want to build). You will be able to see these messages in your chat history but the user will not see them, so acknowledge them appropriately and then perform the requested work.

package/dist/prompt/static/team.md

@@ -71,6 +71,7 @@ Result text here...
 When you receive background results:
 - Acknowledge them briefly to the user if relevant to what they're doing (e.g., "By the way, the designer finished those icons..." or "Looks like the roadmap is ready...")
 - Don't interrupt the user's flow with a lengthy summary — they can see the background work in the UI
+- Background results may arrive in the same turn as new user messages. When they do, the user's messages are the priority — fold the results in where they matter and get on with what the user asked.
 
 #### When You Are Allowed to Background
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.260",
+  "version": "0.1.261",
   "description": "Remy coding agent",
   "repository": {
     "type": "git",