@mindstudio-ai/remy 0.1.148 → 0.1.150

package/dist/headless.js

@@ -4,17 +4,8 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/headless.ts
+// src/headless/index.ts
 import { createInterface } from "readline";
-import {
-  writeFileSync,
-  readFileSync,
-  unlinkSync,
-  mkdirSync,
-  existsSync
-} from "fs";
-import { writeFile } from "fs/promises";
-import { basename, join, extname } from "path";
 
 // src/logger.ts
 import fs from "fs";
@@ -377,11 +368,11 @@ Old tool results are periodically cleared from the conversation to save context
 </conversation_summaries>
 
 <project_onboarding>
-New projects progress through four onboarding states. The user might skip this entirely and jump straight into working on the existing scaffold (which defaults to onboardingFinished), but ideally new projects move through each phase:
+New projects progress through three onboarding states. The user might skip this entirely and jump straight into working on the existing scaffold (which defaults to onboardingFinished), but ideally new projects move through each phase:
 
-- **intake**: Gathering requirements. The project has scaffold code (a "hello world" starter) but it's not the user's app yet. Focus on understanding what they want to build, not on the existing code.
-- **initialSpecAuthoring**: Writing and refining the first spec. The user can see it in the editor as it streams in and can give feedback to iterate on it. This phase covers both the initial draft and any back-and-forth refinement before code generation.
-- **initialCodegen**: First code generation from the spec. The agent is generating methods, tables, interfaces, manifest updates, and scenarios. This can take a while and involves heavy tool use. The user sees a full-screen build progress view.
+- **intake**: Gathering requirements. The project has scaffold code (a "hello world" starter) but it's not the user's app yet. Focus on understanding what they want to build, not on the existing code. Intake ends with a plan proposal via writePlan.
+- **building**: The user approved the initial plan. The agent is writing the spec and building the app. This can take a while and involves heavy tool use (spec authoring, design expert consultation, code generation, verification, polishing).
+- **buildComplete**: The build is done. The frontend is showing the user a reveal experience (pitch deck, app preview). The agent does not need to do anything in this state; the frontend advances to onboardingFinished when the user is ready.
 - **onboardingFinished**: The project is built and ready. Full development mode with all tools available. From here on, keep spec and code in sync as changes are made.
 </project_onboarding>
 
@@ -1298,7 +1289,7 @@ var writePlanTool = {
   clearable: false,
   definition: {
     name: "writePlan",
-    description: "Write an implementation plan for user approval before making changes. Use this only for large, multi-step changes like new features, new interface types, or when the user explicitly asks to see a plan. Most work should be done autonomously without a plan. Write a clear markdown summary of what you intend to do in plain language \u2014 describe the changes from the user's perspective, not as a list of files and code paths. The plan is saved to .remy-plan.md and the user can review, discuss, and approve or reject it. If the user asks for revisions, call this tool again with updated content to overwrite the plan.",
+    description: "Write an implementation plan for user approval before making changes. Use this only for large, multi-step changes like new features, new interface types, or when the user explicitly asks to see a plan. Most work should be done autonomously without a plan. Write a clear markdown summary of what you intend to do in plain language \u2014 describe the changes from the user's perspective, not as a list of files and code paths. The plan is displayed standalone in the UI with approve/reject buttons, so write only the plan itself \u2014 no conversational text, no 'what do you think?', no next-steps narration. Say those things in your chat message instead. If the user asks for revisions, call this tool again with updated content to overwrite the plan.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1368,13 +1359,13 @@ var setProjectOnboardingStateTool = {
   clearable: false,
   definition: {
     name: "setProjectOnboardingState",
-    description: "Advance the project onboarding state. Call at natural transition points: after writing the first draft of the spec (initialSpecReview), before starting the first code generation (initialCodegen), after the first build succeeds (onboardingFinished). Forward-only progression.",
+    description: "Advance the project onboarding state. Only call this when an automated action explicitly instructs you to \u2014 calling it at the wrong time skips stages the user hasn't experienced. Forward-only: building \u2192 buildComplete \u2192 onboardingFinished. `onboardingFinished` is set by the frontend after the user dismisses the reveal; do not call it yourself.",
     inputSchema: {
       type: "object",
       properties: {
         state: {
           type: "string",
-          enum: ["initialSpecReview", "initialCodegen", "onboardingFinished"],
+          enum: ["building", "buildComplete", "onboardingFinished"],
           description: "The onboarding state to advance to."
         }
       },
@@ -2541,7 +2532,7 @@ var runMethodTool = {
   clearable: true,
   definition: {
     name: "runMethod",
-    description: "Run a method in the dev environment and return the result. Use for testing methods after writing or modifying them. Returns output, captured console output, errors with stack traces, and duration. If it fails, check .logs/tunnel.log or .logs/requests.ndjson for more details. Return synchronously - no need to sleep before checking results.",
+    description: 'Run a method in the dev environment and return the result. Use for testing methods after writing or modifying them. Returns output, captured console output, errors with stack traces, and duration. If it fails, check .logs/tunnel.log or .logs/requests.ndjson for more details. Returns synchronously \u2014 no need to sleep before checking results.\n\nBy default methods run unauthenticated. If the method is auth-gated (calls `auth.requireRole()`, filters on `auth.userId`, etc.), pass `userId: "testUser"` to run as the default test user \u2014 no scenario setup required, no userId lookup.',
     inputSchema: {
       type: "object",
       properties: {
@@ -2553,14 +2544,14 @@ var runMethodTool = {
           type: "object",
           description: "The input payload to pass to the method. Omit for methods that take no input."
         },
+        userId: {
+          type: "string",
+          description: 'Optional. Run the method as a specific user. Pass "testUser" to auto-auth as the default test user (the sandbox handles user creation/lookup \u2014 no scenario setup needed). Or pass a real user ID from scenario-seeded data for a specific user. Overrides session-level impersonation for this call only.'
+        },
         roles: {
           type: "array",
           items: { type: "string" },
-          description: 'Optional. Role names for this request (e.g. ["admin"]). Can be used without userId to test role-gated logic. Overrides session-level impersonation for this call only.'
-        },
-        userId: {
-          type: "string",
-          description: "Optional. User ID for this request \u2014 use a managed user's ID to simulate their identity. Overrides session-level impersonation for this call only."
+          description: 'Optional. Role names for this request (e.g. ["admin"]). Combine with `userId` to test a specific role, or use alone to test role-gated logic without a full identity. Overrides session-level impersonation for this call only.'
         }
       },
       required: ["method"]
@@ -2608,10 +2599,10 @@ async function analyzeImage(params) {
 }
 
 // src/tools/_helpers/screenshot.ts
-var SCREENSHOT_ANALYSIS_PROMPT = `Describe everything visible on screen from top to bottom \u2014 every element, its position, its size relative to the viewport, its colors, its content. Be comprehensive, thorough, and spatial. After the inventory, note anything that looks visually broken (overlapping elements, clipped text, misaligned components).
+var SCREENSHOT_ANALYSIS_PROMPT = `Describe everything visible on screen from top to bottom \u2014 every element, its position, its size relative to the viewport, its colors, its content. Be comprehensive, thorough, and spatial. After the inventory, note anything that looks visually broken (overlapping elements, clipped text, misaligned components).`;
+var TEXT_WRAP_DISCLAIMER = `Note: ignore text wrapping issues. Screenshots occasionally show text wrapping onto an extra line compared to the live page \u2014 most noticeable in buttons, badges, and headings. This is a known limitation of SVG foreignObject rendering used the DOM-to-image capture library that took the screenshot. The browser's SVG renderer computes slightly wider text metrics than the HTML layout engine, so text that fits on one line in the live DOM can overflow by a fraction of a pixel in the capture - this is not a real issue.
 
 Respond only with your analysis as Markdown and absolutely no other text. Do not use emojis - use unicode if you need symbols.`;
-var TEXT_WRAP_DISCLAIMER = `Note: ignore text wrapping issues. Screenshots occasionally show text wrapping onto an extra line compared to the live page \u2014 most noticeable in buttons, badges, and headings. This is a known limitation of SVG foreignObject rendering used the DOM-to-image capture library that took the screenshot. The browser's SVG renderer computes slightly wider text metrics than the HTML layout engine, so text that fits on one line in the live DOM can overflow by a fraction of a pixel in the capture - this is not a real issue.`;
 function buildScreenshotAnalysisPrompt(opts) {
   let p = opts?.prompt || SCREENSHOT_ANALYSIS_PROMPT;
   if (opts?.styleMap) {
@@ -2695,23 +2686,22 @@ async function checkBrowserConnected() {
     if (!status.connected) {
       return {
         connected: false,
-        error: "The browser preview is not connected. The user needs to open the preview."
+        reason: BROWSER_UNAVAILABLE_MESSAGE
       };
     }
     return { connected: true };
-  } catch (err) {
+  } catch {
     return {
       connected: false,
-      error: err?.message || "Could not check browser status. The dev environment may not be running."
+      reason: BROWSER_UNAVAILABLE_MESSAGE
     };
   }
 }
+var BROWSER_UNAVAILABLE_MESSAGE = "Browser preview unavailable \u2014 the user has closed their browser and we are continuing to work in the background. This is not a code failure and not something to diagnose. Do not tell the user to click or open anything. Skip the visual check and verify your work through other means: runMethod for backend behavior, queryDatabase for data checks, .logs/devServer.ndjson for build errors, .logs/browser.ndjson for runtime errors, lspDiagnostics for type/syntax, or read the code directly.";
 
 // src/statusWatcher.ts
 function startStatusWatcher(config) {
-  const { apiConfig, getContext, onStatus, interval = 3e3, signal } = config;
-  let lastLabel = "";
-  let lastContext = "";
+  const { apiConfig, getContext, onStatus, interval = 5e3, signal } = config;
   let inflight = false;
   let stopped = false;
   const url = `${apiConfig.baseUrl}/_internal/v2/agent/remy/generate-status`;
@@ -2722,10 +2712,9 @@ function startStatusWatcher(config) {
     inflight = true;
     try {
       const context = getContext();
-      if (!context || context === lastContext) {
+      if (!context) {
         return;
       }
-      lastContext = context;
       const res = await fetch(url, {
         method: "POST",
         headers: {
@@ -2735,15 +2724,11 @@ function startStatusWatcher(config) {
         body: JSON.stringify({ context }),
         signal
       });
-      if (!res.ok) {
+      if (!res.ok || stopped) {
         return;
       }
       const data = await res.json();
-      if (!data.label || data.label === lastLabel) {
-        return;
-      }
-      lastLabel = data.label;
-      if (stopped) {
+      if (!data.label) {
         return;
       }
       onStatus(data.label);
@@ -2763,6 +2748,54 @@ function startStatusWatcher(config) {
   };
 }
 
+// src/automatedActions/sentinel.ts
+function sentinel(name) {
+  return `@@automated::${name}@@`;
+}
+function automatedMessage(name, body) {
+  return body ? `${sentinel(name)}
+${body}` : sentinel(name);
+}
+function hasSentinel(text, name) {
+  return text.startsWith(sentinel(name));
+}
+function isAutomatedMessage(text) {
+  return text.startsWith("@@automated::");
+}
+function parseSentinel(text) {
+  const match = text.match(/^@@automated::(\w+)@@(.*)/s);
+  if (!match) {
+    return null;
+  }
+  return { name: match[1], remainder: match[2] };
+}
+function stripSentinelLine(text) {
+  return text.replace(/^@@automated::[^@]*@@[^\n]*\n?/, "");
+}
+function buildBackgroundResultsMessage(results) {
+  const xml = results.map(
+    (r) => `<tool_result id="${r.toolCallId}" name="${r.name}">
+${r.result}
+</tool_result>`
+  ).join("\n\n");
+  const plural = results.length > 1 ? "s" : "";
+  const body = `This is an automated message containing the result${plural} of ${results.length > 1 ? "tool calls" : "a tool call"} that ${results.length > 1 ? "have" : "has"} been working in the background. This is not a direct message from the user.
+<background_results>
+${xml}
+</background_results>`;
+  return automatedMessage("background_results", body);
+}
+function mergeBackgroundResultsMessages(messages) {
+  const results = [];
+  const toolRe = /<tool_result id="([^"]+)" name="([^"]+)">\n([\s\S]*?)\n<\/tool_result>/g;
+  for (const msg of messages) {
+    for (const m of msg.matchAll(toolRe)) {
+      results.push({ toolCallId: m[1], name: m[2], result: m[3] });
+    }
+  }
+  return buildBackgroundResultsMessage(results);
+}
+
 // src/subagents/common/cleanMessages.ts
 function findLastSummaryCheckpoint(messages, name) {
   for (let i = messages.length - 1; i >= 0; i--) {
@@ -2856,11 +2889,8 @@ ${summaryBlock.text}
     }
     return true;
   }).map((msg) => {
-    if (msg.role === "user" && typeof msg.content === "string" && msg.content.startsWith("@@automated::")) {
-      return {
-        ...msg,
-        content: msg.content.replace(/^@@automated::[^@]*@@[^\n]*\n?/, "")
-      };
+    if (msg.role === "user" && typeof msg.content === "string" && isAutomatedMessage(msg.content)) {
+      return { ...msg, content: stripSentinelLine(msg.content) };
     }
     if (!Array.isArray(msg.content)) {
       return msg;
@@ -2918,7 +2948,7 @@ async function runSubAgent(config) {
   const agentName = subAgentId || "sub-agent";
   const runStart = Date.now();
   log5.info("Sub-agent started", { requestId, parentToolId, agentName });
-  const emit2 = (e) => {
+  const emit = (e) => {
     onEvent({ ...e, parentToolId });
   };
   const dateStr = (/* @__PURE__ */ new Date()).toLocaleDateString("en-US", {
@@ -2983,7 +3013,7 @@ ${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
           }
           return parts.join("\n");
         },
-        onStatus: (label) => emit2({ type: "status", message: label }),
+        onStatus: (label) => emit({ type: "status", message: label }),
         signal
       });
       try {
@@ -3000,7 +3030,7 @@ ${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
             signal
           },
           {
-            onRetry: (attempt) => emit2({
+            onRetry: (attempt) => emit({
               type: "status",
               message: `Lost connection, retrying (attempt ${attempt + 2} of 3)...`
             })
@@ -3021,14 +3051,14 @@ ${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
                   startedAt: event.ts
                 });
               }
-              emit2({ type: "text", text: event.text });
+              emit({ type: "text", text: event.text });
               break;
             }
             case "thinking":
               if (!thinkingStartedAt) {
                 thinkingStartedAt = event.ts;
               }
-              emit2({ type: "thinking", text: event.text });
+              emit({ type: "thinking", text: event.text });
               break;
             case "thinking_complete":
               contentBlocks.push({
@@ -3048,7 +3078,7 @@ ${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
                 input: event.input,
                 startedAt: Date.now()
               });
-              emit2({
+              emit({
                 type: "tool_start",
                 id: event.id,
                 name: event.name,
@@ -3125,7 +3155,7 @@ ${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
               if (externalTools.has(tc.name) && resolveExternalTool) {
                 result = await resolveExternalTool(tc.id, tc.name, input);
               } else {
-                const onLog = (line) => emit2({
+                const onLog = (line) => emit({
                   type: "tool_input_delta",
                   id: tc.id,
                   name: tc.name,
@@ -3176,7 +3206,7 @@ ${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
             durationMs: Date.now() - toolStart,
             isError: r.isError
           });
-          emit2({
+          emit({
             type: "tool_done",
             id: tc.id,
             name: tc.name,
@@ -3445,7 +3475,7 @@ var browserAutomationTool = {
     try {
       const browserStatus = await checkBrowserConnected();
       if (!browserStatus.connected) {
-        return `Error: ${browserStatus.error}`;
+        return browserStatus.reason ?? "Browser preview unavailable.";
       }
       try {
         await sidecarRequest("/reset-browser", {}, { timeout: 5e3 });
@@ -3631,7 +3661,7 @@ var screenshotTool = {
       try {
         const browserStatus = await checkBrowserConnected();
         if (!browserStatus.connected) {
-          return `Error: ${browserStatus.error}`;
+          return browserStatus.reason ?? "Browser preview unavailable.";
         }
         return await captureAndAnalyzeScreenshot({
           prompt: input.prompt,
@@ -3969,7 +3999,7 @@ async function execute5(input, onLog, context) {
   try {
     const browserStatus = await checkBrowserConnected();
     if (!browserStatus.connected) {
-      return `Error: ${browserStatus.error}`;
+      return browserStatus.reason ?? "Browser preview unavailable.";
     }
     return await captureAndAnalyzeScreenshot({
       prompt: input.prompt,
@@ -4402,7 +4432,7 @@ Each interface type invokes the same backend methods. Methods don't know which i
 TypeScript running in a sandboxed environment. Any npm package can be installed. Key capabilities:
 
 - Managed SQLite database with typed schemas and automatic migrations. Define a TypeScript interface, push, and the platform handles diffing and migrating.
-- Built-in app-managed auth. Opt-in via manifest \u2014 developer builds login UI, platform handles verification codes (email/SMS), cookie sessions, and role enforcement. Backend methods use auth.requireRole() for access control.
+- Built-in app-managed auth. Opt-in via manifest \u2014 developer builds login UI, platform handles verification codes (email-code, sms-code) and cookie sessions. API key auth for programmatic access. No OAuth, no social login (no Apple, Google, Facebook, or GitHub sign-in). Backend methods use auth.requireRole() for access control.
 - Encrypted secrets with separate dev/prod values, injected as process.env. For third-party service credentials not covered by the SDK.
 - Git-native deployment. Push to default branch to deploy.
 
@@ -4834,7 +4864,7 @@ Use <current_deck> as your starting point and replace or update the content as n
 - The deck must be a single HTML file \u2014 it will be rendered in an iframe.
 - Must look beautiful on desktop and mobile.
 - Animation between slides must be seamless, no flicker or flashing. For reveal animations: hide elements with CSS \`opacity: 0\` only (no transform in CSS). Let GSAP handle transforms via inline styles and never use \`clearProps\`. Use the existing scaffold, do not write your own transition logic or slide mechanics.
-- Be bold and impactful.
+- Be bold and impactful. Use images from the spec or generate new images when needed.
 - Code must be clean, bug free, and easy to parse. Use GSAP for animations. Pay close attention to layout and alignment to make sure everything is perfect.
 - Keep the progress bar and edge chevrons from the shell \u2014 they are part of the navigation UX.
 
@@ -5532,20 +5562,23 @@ async function runTurn(params) {
           parts.push(`Tool: ${toolName}`);
         }
         if (lastCompletedInput) {
-          parts.push(`Tool input: ${lastCompletedInput.slice(-300)}`);
+          parts.push(`Tool input: ${lastCompletedInput.slice(-1500)}`);
         }
         if (lastCompletedResult) {
-          parts.push(`Tool result: ${lastCompletedResult.slice(-200)}`);
+          parts.push(`Tool result: ${lastCompletedResult.slice(-1500)}`);
         }
-        const text = subAgentText || getTextContent(contentBlocks).slice(-500);
+        const text = subAgentText || getTextContent(contentBlocks).slice(-2e3);
         if (text) {
           parts.push(`Assistant text: ${text}`);
         }
         if (onboardingState && onboardingState !== "onboardingFinished") {
           parts.push(`Build phase: ${onboardingState}`);
         }
-        if (userMessage) {
-          parts.push(`User request: ${userMessage.slice(-100)}`);
+        const automated = parseSentinel(userMessage);
+        if (automated) {
+          parts.push(`Automated action: ${automated.name}`);
+        } else if (userMessage) {
+          parts.push(`User request: ${userMessage.slice(-500)}`);
         }
         return parts.join("\n");
       },
@@ -6005,19 +6038,246 @@ ${partial}` : "[INTERRUPTED] Tool execution was stopped.";
   }
 };
 
+// src/headless/attachments.ts
+import { mkdirSync, existsSync } from "fs";
+import { writeFile } from "fs/promises";
+import { basename, join, extname } from "path";
+var log11 = createLogger("headless:attachments");
+var UPLOADS_DIR = "src/.user-uploads";
+function filenameFromUrl(url) {
+  try {
+    const pathname = new URL(url).pathname;
+    const name = basename(pathname);
+    return name && name !== "/" ? decodeURIComponent(name) : `upload-${Date.now()}`;
+  } catch {
+    return `upload-${Date.now()}`;
+  }
+}
+function resolveUniqueFilename(name) {
+  if (!existsSync(join(UPLOADS_DIR, name))) {
+    return name;
+  }
+  const ext = extname(name);
+  const base = name.slice(0, name.length - ext.length);
+  let counter = 1;
+  while (existsSync(join(UPLOADS_DIR, `${base}-${counter}${ext}`))) {
+    counter++;
+  }
+  return `${base}-${counter}${ext}`;
+}
+var IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".svg",
+  ".bmp",
+  ".ico",
+  ".tiff",
+  ".tif",
+  ".avif",
+  ".heic",
+  ".heif"
+]);
+function isImageAttachment(att) {
+  const name = att.filename || filenameFromUrl(att.url);
+  return IMAGE_EXTENSIONS.has(extname(name).toLowerCase());
+}
+async function persistAttachments(attachments) {
+  const nonVoice = attachments.filter((a) => !a.isVoice);
+  if (nonVoice.length === 0) {
+    return { documents: [], images: [] };
+  }
+  mkdirSync(UPLOADS_DIR, { recursive: true });
+  const results = await Promise.allSettled(
+    nonVoice.map(async (att) => {
+      const name = resolveUniqueFilename(
+        att.filename || filenameFromUrl(att.url)
+      );
+      const localPath = join(UPLOADS_DIR, name);
+      const res = await fetch(att.url, {
+        signal: AbortSignal.timeout(3e4)
+      });
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status} downloading ${att.url}`);
+      }
+      const buffer = Buffer.from(await res.arrayBuffer());
+      await writeFile(localPath, buffer);
+      log11.info("Attachment saved", {
+        filename: name,
+        path: localPath,
+        bytes: buffer.length
+      });
+      let extractedTextPath;
+      if (att.extractedTextUrl) {
+        try {
+          const textRes = await fetch(att.extractedTextUrl, {
+            signal: AbortSignal.timeout(3e4)
+          });
+          if (textRes.ok) {
+            extractedTextPath = `${localPath}.txt`;
+            await writeFile(extractedTextPath, await textRes.text(), "utf-8");
+            log11.info("Extracted text saved", { path: extractedTextPath });
+          }
+        } catch {
+        }
+      }
+      return {
+        filename: name,
+        localPath,
+        remoteUrl: att.url,
+        extractedTextPath
+      };
+    })
+  );
+  const settled = results.map((r, i) => ({
+    result: r.status === "fulfilled" ? r.value : null,
+    isImage: isImageAttachment(nonVoice[i])
+  }));
+  return {
+    documents: settled.filter((s) => !s.isImage).map((s) => s.result),
+    images: settled.filter((s) => s.isImage).map((s) => s.result)
+  };
+}
+function buildUploadHeader(results) {
+  const succeeded = results.filter(Boolean);
+  if (succeeded.length === 0) {
+    return "";
+  }
+  if (succeeded.length === 1) {
+    const r = succeeded[0];
+    const parts = [`[Uploaded file: ${r.localPath} (CDN: ${r.remoteUrl})`];
+    if (r.extractedTextPath) {
+      parts.push(`extracted text: ${r.extractedTextPath}`);
+    }
+    return parts.join(" \u2014 ") + "]";
+  }
+  const lines = succeeded.map((r) => {
+    const parts = [`- ${r.localPath} (CDN: ${r.remoteUrl})`];
+    if (r.extractedTextPath) {
+      parts.push(`  extracted text: ${r.extractedTextPath}`);
+    }
+    return parts.join("\n");
+  });
+  return `[Uploaded files]
+${lines.join("\n")}`;
+}
+
+// src/headless/planFile.ts
+import { readFileSync, writeFileSync, unlinkSync } from "fs";
+var PLAN_FILE3 = ".remy-plan.md";
+function applyPlanFileSideEffect(rawText) {
+  if (hasSentinel(rawText, "approvePlan") || hasSentinel(rawText, "approveInitialPlan")) {
+    try {
+      const plan = readFileSync(PLAN_FILE3, "utf-8");
+      writeFileSync(
+        PLAN_FILE3,
+        plan.replace(/^status:\s*pending/m, "status: approved"),
+        "utf-8"
+      );
+    } catch {
+    }
+  } else if (hasSentinel(rawText, "rejectPlan")) {
+    try {
+      unlinkSync(PLAN_FILE3);
+    } catch {
+    }
+  }
+}
+
+// src/headless/stats.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+var STATS_FILE = ".remy-stats.json";
+function createSessionStats() {
+  return {
+    messageCount: 0,
+    turns: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalCacheCreationTokens: 0,
+    totalCacheReadTokens: 0,
+    lastContextSize: 0,
+    compactionInProgress: false,
+    updatedAt: 0
+  };
+}
+function loadQueue() {
+  try {
+    const stats = JSON.parse(readFileSync2(STATS_FILE, "utf-8"));
+    if (Array.isArray(stats.queue)) {
+      return stats.queue;
+    }
+  } catch {
+  }
+  return [];
+}
+function writeStats(stats, queue) {
+  try {
+    writeFileSync2(
+      STATS_FILE,
+      JSON.stringify({
+        ...stats,
+        queue
+      })
+    );
+  } catch {
+  }
+}
+
+// src/headless/messageQueue.ts
+var MessageQueue = class {
+  items = [];
+  onChange;
+  constructor(initial = [], onChange) {
+    this.items = [...initial];
+    this.onChange = onChange;
+  }
+  push(item) {
+    this.items.push(item);
+    this.onChange?.();
+  }
+  shift() {
+    const item = this.items.shift();
+    if (item) {
+      this.onChange?.();
+    }
+    return item;
+  }
+  /** Remove and return all queued items. */
+  drain() {
+    if (this.items.length === 0) {
+      return [];
+    }
+    const all = this.items.splice(0);
+    this.onChange?.();
+    return all;
+  }
+  /** Copy of current queue contents (for surfacing on events). */
+  snapshot() {
+    return [...this.items];
+  }
+  /** Return the next item without removing it. */
+  peek() {
+    return this.items[0];
+  }
+  get length() {
+    return this.items.length;
+  }
+};
+
 // src/automatedActions/resolve.ts
 var NON_ACTION_SENTINELS = /* @__PURE__ */ new Set(["background_results"]);
 function resolveAction(text) {
-  const match = text.match(/^@@automated::(\w+)@@(.*)/s);
-  if (!match) {
+  const parsed = parseSentinel(text);
+  if (!parsed) {
     return null;
   }
-  const triggerName = match[1];
+  const { name: triggerName, remainder } = parsed;
   if (NON_ACTION_SENTINELS.has(triggerName)) {
     return null;
   }
   let params = {};
-  const remainder = match[2];
   if (remainder) {
     try {
       params = JSON.parse(remainder.split("\n")[0]);
@@ -6039,114 +6299,155 @@ function resolveAction(text) {
     body = body.replaceAll(`{{${key}}}`, str);
   }
   return {
-    message: `@@automated::${triggerName}@@
-${body}`,
+    message: automatedMessage(triggerName, body),
     next
   };
 }
 
-// src/headless.ts
-var log11 = createLogger("headless");
-function emit(event, data, requestId) {
-  const payload = { event, ...data };
-  if (requestId) {
-    payload.requestId = requestId;
-  }
-  process.stdout.write(JSON.stringify(payload) + "\n");
-}
-function handleClear(state) {
-  clearSession(state);
-  return {};
-}
-function handleCancel(currentAbort, pendingTools) {
-  if (currentAbort) {
-    currentAbort.abort();
-  }
-  for (const [id, pending] of pendingTools) {
-    clearTimeout(pending.timeout);
-    pending.resolve("Error: cancelled");
-    pendingTools.delete(id);
-  }
-  return {};
-}
-function dispatchSimple(requestId, eventName, handler) {
-  try {
-    const data = handler();
-    if (eventName) {
-      emit(eventName, data, requestId);
+// src/headless/index.ts
+var log12 = createLogger("headless");
+var EXTERNAL_TOOL_TIMEOUT_MS = 3e5;
+var USER_FACING_TOOLS = /* @__PURE__ */ new Set([
+  "promptUser",
+  "confirmDestructiveAction",
+  "presentPublishPlan"
+]);
+var HeadlessSession = class {
+  // Configuration
+  opts;
+  config;
+  // Conversation state
+  state = createAgentState();
+  sessionStats = createSessionStats();
+  // Turn lifecycle
+  running = false;
+  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. */
+  completedEmitted = false;
+  turnStart = 0;
+  /**
+   * Onboarding state of the currently-running turn. Captured at runSingleTurn
+   * start so onBackgroundComplete can enqueue background results with the
+   * right state (the triggering turn's state, not a stale one).
+   */
+  currentOnboardingState;
+  /**
+   * Unified message queue. Holds pending work to deliver after the current
+   * turn completes: chained automated actions, background sub-agent results,
+   * and user messages sent while a turn is running. Strict FIFO. Persisted
+   * to .remy-stats.json so queued work survives process restarts.
+   */
+  queue;
+  // External tool bridge
+  pendingTools = /* @__PURE__ */ new Map();
+  earlyResults = /* @__PURE__ */ new Map();
+  // Tool block updates from background completions (separate from the message queue)
+  pendingBlockUpdates = [];
+  // Tool lifecycle management — shared across all nesting depths
+  toolRegistry = new ToolRegistry();
+  // IO
+  readline = null;
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  //////////////////////////////////////////////////////////////////////////////
+  // Lifecycle
+  //////////////////////////////////////////////////////////////////////////////
+  async start() {
+    const stderrWrite = (...args) => {
+      process.stderr.write(args.map(String).join(" ") + "\n");
+    };
+    console.log = stderrWrite;
+    console.warn = stderrWrite;
+    console.info = stderrWrite;
+    if (this.opts.lspUrl) {
+      setLspBaseUrl(this.opts.lspUrl);
+    }
+    this.config = resolveConfig({
+      apiKey: this.opts.apiKey,
+      baseUrl: this.opts.baseUrl
+    });
+    const resumed = loadSession(this.state);
+    this.queue = new MessageQueue(loadQueue(), () => this.persistStats());
+    if (resumed) {
+      this.emit("session_restored", {
+        messageCount: this.state.messages.length,
+        ...this.queueFields()
+      });
     }
-    emit("completed", { success: true }, requestId);
-  } catch (err) {
-    emit("completed", { success: false, error: err.message }, requestId);
+    this.toolRegistry.onEvent = this.onEvent;
+    this.readline = createInterface({ input: process.stdin });
+    this.readline.on("line", this.handleStdinLine);
+    this.readline.on("close", () => {
+      this.emit("stopping");
+      this.emit("stopped");
+      process.exit(0);
+    });
+    process.on("SIGTERM", this.shutdown);
+    process.on("SIGINT", this.shutdown);
+    this.emit("ready", this.queueFields());
   }
-}
-async function startHeadless(opts = {}) {
-  const stderrWrite = (...args) => {
-    process.stderr.write(args.map(String).join(" ") + "\n");
-  };
-  console.log = stderrWrite;
-  console.warn = stderrWrite;
-  console.info = stderrWrite;
-  if (opts.lspUrl) {
-    setLspBaseUrl(opts.lspUrl);
-  }
-  const config = resolveConfig({
-    apiKey: opts.apiKey,
-    baseUrl: opts.baseUrl
-  });
-  const state = createAgentState();
-  const resumed = loadSession(state);
-  if (resumed) {
-    emit("session_restored", { messageCount: state.messages.length });
-  }
-  let running = false;
-  let currentAbort = null;
-  let currentRequestId;
-  let completedEmitted = false;
-  let turnStart = 0;
-  let pendingNextAction;
-  const EXTERNAL_TOOL_TIMEOUT_MS = 3e5;
-  const pendingTools = /* @__PURE__ */ new Map();
-  const earlyResults = /* @__PURE__ */ new Map();
-  const toolRegistry = new ToolRegistry();
-  const sessionStats = {
-    messageCount: 0,
-    turns: 0,
-    totalInputTokens: 0,
-    totalOutputTokens: 0,
-    totalCacheCreationTokens: 0,
-    totalCacheReadTokens: 0,
-    lastContextSize: 0,
-    compactionInProgress: false,
-    updatedAt: 0
+  shutdown = () => {
+    this.emit("stopping");
+    this.emit("stopped");
+    process.exit(0);
   };
-  const backgroundQueue = [];
-  function flushBackgroundQueue() {
-    if (backgroundQueue.length === 0) {
-      return;
+  //////////////////////////////////////////////////////////////////////////////
+  // Wire protocol
+  //////////////////////////////////////////////////////////////////////////////
+  emit(event, data, requestId) {
+    const payload = { event, ...data };
+    if (requestId) {
+      payload.requestId = requestId;
     }
-    const results = backgroundQueue.splice(0);
-    const xmlParts = results.map(
-      (r) => `<tool_result id="${r.toolCallId}" name="${r.name}">
-${r.result}
-</tool_result>`
-    ).join("\n\n");
-    const message = `@@automated::background_results@@
-This is an automated message containing the result of a tool call that has been working in the background. This is not a direct message from the user.
-<background_results>
-${xmlParts}
-</background_results>`;
-    const bgRequestId = `bg-${Date.now()}`;
-    handleMessage({ action: "message", text: message }, bgRequestId);
+    process.stdout.write(JSON.stringify(payload) + "\n");
   }
-  const pendingBlockUpdates = [];
-  function applyPendingBlockUpdates() {
-    if (pendingBlockUpdates.length === 0) {
+  /**
+   * Emit a `completed` event and mark completedEmitted. Includes
+   * `queuedMessages` if the queue has items (sandbox uses this to know the
+   * agent is still busy with pipeline work).
+   */
+  emitCompleted(rid, data) {
+    this.emit("completed", { ...data, ...this.queueFields() }, rid);
+    this.completedEmitted = true;
+  }
+  /** Returns `{ queuedMessages }` when the queue is non-empty, else empty object. */
+  queueFields() {
+    return this.queue.length > 0 ? { queuedMessages: this.queue.snapshot() } : {};
+  }
+  /** Dispatch a simple (non-streaming) command: call handler, emit response + completed. */
+  dispatchSimple(requestId, eventName, handler) {
+    try {
+      const data = handler();
+      if (eventName) {
+        this.emit(eventName, data, requestId);
+      }
+      this.emit("completed", { success: true }, requestId);
+    } catch (err) {
+      this.emit("completed", { success: false, error: err.message }, requestId);
+    }
+  }
+  //////////////////////////////////////////////////////////////////////////////
+  // Stats + queue persistence
+  //////////////////////////////////////////////////////////////////////////////
+  /** Persist sessionStats + queue snapshot to .remy-stats.json. */
+  persistStats() {
+    this.sessionStats.updatedAt = Date.now();
+    writeStats(this.sessionStats, this.queue.snapshot());
+  }
+  //////////////////////////////////////////////////////////////////////////////
+  // Background completions (tool-block mutation; message delivery via queue)
+  //////////////////////////////////////////////////////////////////////////////
+  /** Apply queued tool block updates to state.messages. Safe to call any time. */
+  applyPendingBlockUpdates() {
+    if (this.pendingBlockUpdates.length === 0) {
       return;
     }
-    const updates = pendingBlockUpdates.splice(0);
+    const updates = this.pendingBlockUpdates.splice(0);
     for (const update of updates) {
-      for (const msg of state.messages) {
+      for (const msg of this.state.messages) {
         if (!Array.isArray(msg.content)) {
           continue;
         }
@@ -6161,60 +6462,65 @@ ${xmlParts}
         }
       }
     }
+    saveSession(this.state);
   }
-  function applyPendingSummaries() {
+  /** Drain pending compaction summaries and insert at a safe point. */
+  applyPendingSummaries() {
     const summaries = getPendingSummaries();
     if (summaries.length === 0) {
       return;
     }
-    const idx = findSafeInsertionPoint(state.messages);
-    state.messages.splice(idx, 0, ...summaries);
-    saveSession(state);
+    const idx = findSafeInsertionPoint(this.state.messages);
+    this.state.messages.splice(idx, 0, ...summaries);
+    saveSession(this.state);
   }
-  function onBackgroundComplete(toolCallId, name, result, subAgentMessages) {
-    pendingBlockUpdates.push({ toolCallId, result, subAgentMessages });
-    log11.info("Background complete", {
+  onBackgroundComplete = (toolCallId, name, result, subAgentMessages) => {
+    this.pendingBlockUpdates.push({ toolCallId, result, subAgentMessages });
+    log12.info("Background complete", {
       toolCallId,
       name,
-      requestId: currentRequestId
+      requestId: this.currentRequestId
     });
-    onEvent({
+    this.onEvent({
       type: "tool_background_complete",
       id: toolCallId,
       name,
       result
     });
-    backgroundQueue.push({
-      toolCallId,
-      name,
-      result,
-      completedAt: Date.now()
+    this.queue.push({
+      command: {
+        action: "message",
+        text: buildBackgroundResultsMessage([{ toolCallId, name, result }]),
+        ...this.currentOnboardingState && {
+          onboardingState: this.currentOnboardingState
+        }
+      },
+      source: "background",
+      enqueuedAt: Date.now()
     });
-    if (!running) {
-      applyPendingBlockUpdates();
-      flushBackgroundQueue();
+    if (!this.running) {
+      this.applyPendingBlockUpdates();
+      this.kickDrain();
     }
-  }
-  const USER_FACING_TOOLS = /* @__PURE__ */ new Set([
-    "promptUser",
-    "confirmDestructiveAction",
-    "presentPublishPlan"
-  ]);
-  function resolveExternalTool(id, name, _input) {
-    const early = earlyResults.get(id);
+  };
+  //////////////////////////////////////////////////////////////////////////////
+  // External tool bridge
+  //////////////////////////////////////////////////////////////////////////////
+  resolveExternalTool = (id, name, _input) => {
+    const early = this.earlyResults.get(id);
     if (early !== void 0) {
-      earlyResults.delete(id);
+      this.earlyResults.delete(id);
       return Promise.resolve(early);
     }
     const shouldTimeout = !USER_FACING_TOOLS.has(name);
     return new Promise((resolve2) => {
       const timeout = shouldTimeout ? setTimeout(() => {
-        pendingTools.delete(id);
+        this.pendingTools.delete(id);
         resolve2(
           "Error: Tool timed out \u2014 no response from the app environment after 5 minutes."
         );
       }, EXTERNAL_TOOL_TIMEOUT_MS) : void 0;
-      pendingTools.set(id, {
+      this.pendingTools.set(id, {
         resolve: (result) => {
           clearTimeout(timeout);
           resolve2(result);
@@ -6222,57 +6528,51 @@ ${xmlParts}
         timeout
       });
     });
-  }
-  function onEvent(e) {
-    const rid = currentRequestId;
+  };
+  //////////////////////////////////////////////////////////////////////////////
+  // AgentEvent → wire protocol translation
+  //////////////////////////////////////////////////////////////////////////////
+  onEvent = (e) => {
+    const rid = this.currentRequestId;
     switch (e.type) {
       case "turn_started":
-        emit("turn_started", {}, rid);
+        this.emit("turn_started", {}, rid);
+        return;
+      case "user_message":
+        this.emit("user_message", { text: e.text }, rid);
         return;
-      // Terminal events — translate to `completed`
+      // Terminal events — translate to `completed`.
+      // Post-turn queue drain happens in handleMessage AFTER runTurn returns,
+      // so that `running` is held across the drain and no user message can
+      // slip in mid-pipeline.
       case "turn_done":
-        completedEmitted = true;
         if (e.stats) {
-          sessionStats.turns++;
-          sessionStats.totalInputTokens += e.stats.inputTokens;
-          sessionStats.totalOutputTokens += e.stats.outputTokens;
-          sessionStats.totalCacheCreationTokens += e.stats.cacheCreationTokens ?? 0;
-          sessionStats.totalCacheReadTokens += e.stats.cacheReadTokens ?? 0;
-          sessionStats.lastContextSize = e.stats.lastCallInputTokens ?? e.stats.inputTokens;
-        }
-        sessionStats.messageCount = state.messages.length;
-        sessionStats.updatedAt = Date.now();
-        try {
-          writeFileSync(".remy-stats.json", JSON.stringify(sessionStats));
-        } catch {
+          this.sessionStats.turns++;
+          this.sessionStats.totalInputTokens += e.stats.inputTokens;
+          this.sessionStats.totalOutputTokens += e.stats.outputTokens;
+          this.sessionStats.totalCacheCreationTokens += e.stats.cacheCreationTokens ?? 0;
+          this.sessionStats.totalCacheReadTokens += e.stats.cacheReadTokens ?? 0;
+          this.sessionStats.lastContextSize = e.stats.lastCallInputTokens ?? e.stats.inputTokens;
         }
-        emit(
+        this.sessionStats.messageCount = this.state.messages.length;
+        this.persistStats();
+        this.emitCompleted(rid, {
+          success: true,
+          durationMs: Date.now() - this.turnStart
+        });
+        return;
+      case "turn_cancelled": {
+        this.emit(
           "completed",
-          { success: true, durationMs: Date.now() - turnStart },
+          { success: false, error: "cancelled", ...this.queueFields() },
           rid
         );
-        setTimeout(() => {
-          applyPendingSummaries();
-          applyPendingBlockUpdates();
-          flushBackgroundQueue();
-          if (pendingNextAction) {
-            const next = pendingNextAction;
-            pendingNextAction = void 0;
-            handleMessage(
-              { action: "message", text: `@@automated::${next}@@` },
-              `chain-${Date.now()}`
-            );
-          }
-        }, 0);
-        return;
-      case "turn_cancelled":
-        completedEmitted = true;
-        pendingNextAction = void 0;
-        emit("completed", { success: false, error: "cancelled" }, rid);
+        this.completedEmitted = true;
         return;
+      }
       // Streaming events — forward with requestId
       case "text":
-        emit(
+        this.emit(
           "text",
           {
             text: e.text,
@@ -6282,7 +6582,7 @@ ${xmlParts}
         );
         return;
       case "thinking":
-        emit(
+        this.emit(
           "thinking",
           {
             text: e.text,
@@ -6292,7 +6592,7 @@ ${xmlParts}
         );
         return;
       case "tool_input_delta":
-        emit(
+        this.emit(
           "tool_input_delta",
           {
             id: e.id,
@@ -6304,7 +6604,7 @@ ${xmlParts}
         );
         return;
       case "tool_start":
-        emit(
+        this.emit(
           "tool_start",
           {
             id: e.id,
@@ -6318,7 +6618,7 @@ ${xmlParts}
         );
         return;
       case "tool_done":
-        emit(
+        this.emit(
           "tool_done",
           {
             id: e.id,
@@ -6331,7 +6631,7 @@ ${xmlParts}
         );
         return;
       case "tool_background_complete":
-        emit(
+        this.emit(
           "tool_background_complete",
           {
             id: e.id,
@@ -6343,7 +6643,7 @@ ${xmlParts}
         );
         return;
       case "tool_stopped":
-        emit(
+        this.emit(
           "tool_stopped",
           {
             id: e.id,
@@ -6355,7 +6655,7 @@ ${xmlParts}
         );
         return;
       case "tool_restarted":
-        emit(
+        this.emit(
           "tool_restarted",
           {
             id: e.id,
@@ -6367,7 +6667,7 @@ ${xmlParts}
         );
         return;
       case "status":
-        emit(
+        this.emit(
           "status",
           {
             message: e.message,
@@ -6377,147 +6677,27 @@ ${xmlParts}
         );
         return;
       case "error":
-        emit("error", { error: e.error }, rid);
+        this.emit("error", { error: e.error }, rid);
         return;
     }
-  }
-  toolRegistry.onEvent = onEvent;
-  const UPLOADS_DIR = "src/.user-uploads";
-  function filenameFromUrl(url) {
-    try {
-      const pathname = new URL(url).pathname;
-      const name = basename(pathname);
-      return name && name !== "/" ? decodeURIComponent(name) : `upload-${Date.now()}`;
-    } catch {
-      return `upload-${Date.now()}`;
-    }
-  }
-  function resolveUniqueFilename(name) {
-    if (!existsSync(join(UPLOADS_DIR, name))) {
-      return name;
-    }
-    const ext = extname(name);
-    const base = name.slice(0, name.length - ext.length);
-    let counter = 1;
-    while (existsSync(join(UPLOADS_DIR, `${base}-${counter}${ext}`))) {
-      counter++;
-    }
-    return `${base}-${counter}${ext}`;
-  }
-  const IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
-    ".png",
-    ".jpg",
-    ".jpeg",
-    ".gif",
-    ".webp",
-    ".svg",
-    ".bmp",
-    ".ico",
-    ".tiff",
-    ".tif",
-    ".avif",
-    ".heic",
-    ".heif"
-  ]);
-  function isImageAttachment(att) {
-    const name = att.filename || filenameFromUrl(att.url);
-    return IMAGE_EXTENSIONS.has(extname(name).toLowerCase());
-  }
-  async function persistAttachments(attachments) {
-    const nonVoice = attachments.filter((a) => !a.isVoice);
-    if (nonVoice.length === 0) {
-      return { documents: [], images: [] };
-    }
-    mkdirSync(UPLOADS_DIR, { recursive: true });
-    const results = await Promise.allSettled(
-      nonVoice.map(async (att) => {
-        const name = resolveUniqueFilename(
-          att.filename || filenameFromUrl(att.url)
-        );
-        const localPath = join(UPLOADS_DIR, name);
-        const res = await fetch(att.url, {
-          signal: AbortSignal.timeout(3e4)
-        });
-        if (!res.ok) {
-          throw new Error(`HTTP ${res.status} downloading ${att.url}`);
-        }
-        const buffer = Buffer.from(await res.arrayBuffer());
-        await writeFile(localPath, buffer);
-        log11.info("Attachment saved", {
-          filename: name,
-          path: localPath,
-          bytes: buffer.length
-        });
-        let extractedTextPath;
-        if (att.extractedTextUrl) {
-          try {
-            const textRes = await fetch(att.extractedTextUrl, {
-              signal: AbortSignal.timeout(3e4)
-            });
-            if (textRes.ok) {
-              extractedTextPath = `${localPath}.txt`;
-              await writeFile(extractedTextPath, await textRes.text(), "utf-8");
-              log11.info("Extracted text saved", { path: extractedTextPath });
-            }
-          } catch {
-          }
-        }
-        return { filename: name, localPath, extractedTextPath };
-      })
-    );
-    const settled = results.map((r, i) => ({
-      result: r.status === "fulfilled" ? r.value : null,
-      isImage: isImageAttachment(nonVoice[i])
-    }));
-    return {
-      documents: settled.filter((s) => !s.isImage).map((s) => s.result),
-      images: settled.filter((s) => s.isImage).map((s) => s.result)
-    };
-  }
-  function buildUploadHeader(results) {
-    const succeeded = results.filter(Boolean);
-    if (succeeded.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 lines = succeeded.map((r) => {
-      if (r.extractedTextPath) {
-        return `- ${r.localPath} (extracted text: ${r.extractedTextPath})`;
-      }
-      return `- ${r.localPath}`;
-    });
-    return `[Uploaded files]
-${lines.join("\n")}`;
-  }
-  async function handleMessage(parsed, requestId) {
-    if (running) {
-      emit(
-        "error",
-        { error: "Agent is already processing a message" },
-        requestId
-      );
-      emit(
-        "completed",
-        { success: false, error: "Agent is already processing a message" },
-        requestId
-      );
-      return;
-    }
-    running = true;
-    currentRequestId = requestId;
-    currentAbort = new AbortController();
-    completedEmitted = false;
-    turnStart = Date.now();
+  };
+  //////////////////////////////////////////////////////////////////////////////
+  // 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.
+   */
+  async runSingleTurn(parsed, requestId) {
+    this.currentRequestId = requestId;
+    this.currentAbort = new AbortController();
+    this.completedEmitted = false;
+    this.turnStart = Date.now();
     const attachments = parsed.attachments;
     if (attachments?.length) {
-      log11.info("Message has attachments", {
+      log12.info("Message has attachments", {
         count: attachments.length,
         urls: attachments.map((a) => a.url)
       });
@@ -6534,143 +6714,266 @@ ${lines.join("\n")}`;
 ${userMessage}` : header;
         }
       } catch (err) {
-        log11.warn("Attachment persistence failed", { error: err.message });
+        log12.warn("Attachment persistence failed", { error: err.message });
       }
     }
     let resolved = null;
     try {
       resolved = resolveAction(userMessage);
     } catch (err) {
-      emit(
-        "completed",
-        { success: false, error: err.message || "Failed to resolve action" },
-        requestId
-      );
+      this.emitCompleted(requestId, {
+        success: false,
+        error: err.message || "Failed to resolve action"
+      });
       return;
     }
-    pendingNextAction = void 0;
     if (resolved !== null) {
       userMessage = resolved.message;
-      pendingNextAction = resolved.next;
     }
     const isHidden = resolved !== null || !!parsed.hidden;
-    const rawText = parsed.text ?? "";
-    if (rawText.startsWith("@@automated::approvePlan@@")) {
-      try {
-        const plan = readFileSync(".remy-plan.md", "utf-8");
-        writeFileSync(
-          ".remy-plan.md",
-          plan.replace(/^status:\s*pending/m, "status: approved"),
-          "utf-8"
-        );
-      } catch {
-      }
-    } else if (rawText.startsWith("@@automated::rejectPlan@@")) {
-      try {
-        unlinkSync(".remy-plan.md");
-      } catch {
-      }
-    }
+    applyPlanFileSideEffect(parsed.text ?? "");
     const onboardingState = parsed.onboardingState ?? "onboardingFinished";
+    this.currentOnboardingState = onboardingState;
     const system = buildSystemPrompt(
       onboardingState,
       parsed.viewContext
     );
+    if (resolved?.next) {
+      this.queue.push({
+        command: {
+          action: "message",
+          text: sentinel(resolved.next),
+          onboardingState
+        },
+        source: "chain",
+        enqueuedAt: Date.now()
+      });
+    }
     try {
       await runTurn({
-        state,
+        state: this.state,
         userMessage,
         attachments,
-        apiConfig: config,
+        apiConfig: this.config,
         system,
-        model: opts.model,
+        model: this.opts.model,
         onboardingState,
         requestId,
-        signal: currentAbort.signal,
-        onEvent,
-        resolveExternalTool,
+        signal: this.currentAbort.signal,
+        onEvent: this.onEvent,
+        resolveExternalTool: this.resolveExternalTool,
         hidden: isHidden,
-        toolRegistry,
-        onBackgroundComplete
+        toolRegistry: this.toolRegistry,
+        onBackgroundComplete: this.onBackgroundComplete
       });
-      if (!completedEmitted) {
-        emit(
-          "completed",
-          { success: false, error: "Turn ended unexpectedly" },
-          requestId
-        );
+      if (!this.completedEmitted) {
+        this.emitCompleted(requestId, {
+          success: false,
+          error: "Turn ended unexpectedly"
+        });
       }
-      log11.info("Turn complete", {
+      log12.info("Turn complete", {
         requestId,
-        durationMs: Date.now() - turnStart
+        durationMs: Date.now() - this.turnStart
       });
     } catch (err) {
-      if (!completedEmitted) {
-        emit("error", { error: err.message }, requestId);
-        emit("completed", { success: false, error: err.message }, requestId);
+      if (!this.completedEmitted) {
+        this.emit("error", { error: err.message }, requestId);
+        this.emitCompleted(requestId, {
+          success: false,
+          error: err.message
+        });
       }
-      log11.warn("Command failed", {
+      log12.warn("Command failed", {
         action: "message",
         requestId,
         error: err.message
       });
+      this.queue.drain();
+    }
+    this.applyPendingSummaries();
+    this.applyPendingBlockUpdates();
+  }
+  async handleMessage(parsed, requestId) {
+    if (this.running) {
+      const command = { ...parsed };
+      if (requestId && command.requestId === void 0) {
+        command.requestId = requestId;
+      }
+      this.queue.push({
+        command,
+        source: "user",
+        enqueuedAt: Date.now()
+      });
+      this.emit(
+        "queued",
+        { position: this.queue.length, ...this.queueFields() },
+        requestId
+      );
+      return;
+    }
+    this.running = true;
+    try {
+      await this.runSingleTurn(parsed, requestId);
+      await this.drainQueueLoop();
+    } finally {
+      this.currentAbort = null;
+      this.currentRequestId = void 0;
+      this.running = false;
+    }
+  }
+  /**
+   * 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.
+   */
+  async drainQueueLoop() {
+    while (true) {
+      const next = this.queue.shift();
+      if (!next) {
+        break;
+      }
+      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()}`);
+        continue;
+      }
+      const nextRid = next.command.requestId ?? `${next.source}-${Date.now()}`;
+      await this.runSingleTurn(next.command, nextRid);
+    }
+  }
+  /**
+   * Resume draining the queue when the agent is idle. Acquires the lock,
+   * drains, releases. Used by the `resume` stdin action (sandbox-initiated)
+   * and by kickDrain (background-completion-initiated).
+   */
+  async resumeQueue() {
+    if (this.running || this.queue.length === 0) {
+      return;
+    }
+    this.running = true;
+    try {
+      await this.drainQueueLoop();
+    } finally {
+      this.currentAbort = null;
+      this.currentRequestId = void 0;
+      this.running = false;
     }
-    currentAbort = null;
-    currentRequestId = void 0;
-    running = false;
   }
-  const rl = createInterface({ input: process.stdin });
-  rl.on("line", async (line) => {
+  /**
+   * Kick off drainage of the queue when the agent is idle. Used by
+   * onBackgroundComplete (when !running) to deliver results without
+   * racing any currently-synchronous path.
+   */
+  kickDrain() {
+    if (this.running || this.queue.length === 0) {
+      return;
+    }
+    setTimeout(() => this.resumeQueue(), 0);
+  }
+  //////////////////////////////////////////////////////////////////////////////
+  // Simple command handlers
+  //////////////////////////////////////////////////////////////////////////////
+  handleClear() {
+    clearSession(this.state);
+    return {};
+  }
+  /** Cancel the running turn and drain the queue. Returns the drained items. */
+  handleCancel() {
+    if (this.currentAbort) {
+      this.currentAbort.abort();
+    }
+    for (const [id, pending] of this.pendingTools) {
+      clearTimeout(pending.timeout);
+      pending.resolve("Error: cancelled");
+      this.pendingTools.delete(id);
+    }
+    return this.queue.drain();
+  }
+  //////////////////////////////////////////////////////////////////////////////
+  // Stdin router
+  //////////////////////////////////////////////////////////////////////////////
+  handleStdinLine = async (line) => {
     let parsed;
     try {
       parsed = JSON.parse(line);
     } catch {
-      emit("error", { error: "Invalid JSON on stdin" });
+      this.emit("error", { error: "Invalid JSON on stdin" });
       return;
     }
     const { action, requestId } = parsed;
-    log11.info("Command received", { action, requestId });
+    log12.info("Command received", { action, requestId });
     if (action === "tool_result" && parsed.id) {
       const id = parsed.id;
       const result = parsed.result ?? "";
-      const pending = pendingTools.get(id);
+      const pending = this.pendingTools.get(id);
       if (pending) {
-        pendingTools.delete(id);
+        this.pendingTools.delete(id);
         pending.resolve(result);
-      } else if (!running) {
-        log11.info("Late tool_result while idle, dismissing", { id });
-        emit("completed", { success: true }, requestId);
+      } else if (!this.running) {
+        log12.info("Late tool_result while idle, dismissing", { id });
+        this.emit("completed", { success: true }, requestId);
       } else {
-        earlyResults.set(id, result);
+        this.earlyResults.set(id, result);
       }
       return;
     }
     if (action === "get_history") {
-      applyPendingBlockUpdates();
-      dispatchSimple(requestId, "history", () => ({
-        messages: state.messages,
-        running,
-        ...running && currentRequestId ? { currentRequestId } : {}
+      this.applyPendingBlockUpdates();
+      this.dispatchSimple(requestId, "history", () => ({
+        messages: this.state.messages,
+        running: this.running,
+        ...this.running && this.currentRequestId ? { currentRequestId: this.currentRequestId } : {},
+        ...this.queueFields()
       }));
       return;
     }
     if (action === "clear") {
-      dispatchSimple(requestId, "session_cleared", () => handleClear(state));
+      this.dispatchSimple(
+        requestId,
+        "session_cleared",
+        () => this.handleClear()
+      );
       return;
     }
     if (action === "cancel") {
-      handleCancel(currentAbort, pendingTools);
-      emit("completed", { success: true }, requestId);
+      const cancelled = this.handleCancel();
+      this.emit(
+        "completed",
+        {
+          success: true,
+          ...cancelled.length > 0 && { cancelledMessages: cancelled }
+        },
+        requestId
+      );
       return;
     }
     if (action === "stop_tool") {
       const id = parsed.id;
       const mode = parsed.mode ?? "hard";
-      const found = toolRegistry.stop(id, mode);
+      const found = this.toolRegistry.stop(id, mode);
       if (found) {
-        emit("completed", { success: true }, requestId);
+        this.emit("completed", { success: true }, requestId);
       } else {
-        emit(
+        this.emit(
           "completed",
           { success: false, error: "Tool not found" },
           requestId
@@ -6681,11 +6984,11 @@ ${userMessage}` : header;
     if (action === "restart_tool") {
       const id = parsed.id;
       const patchedInput = parsed.input;
-      const found = toolRegistry.restart(id, patchedInput);
+      const found = this.toolRegistry.restart(id, patchedInput);
       if (found) {
-        emit("completed", { success: true }, requestId);
+        this.emit("completed", { success: true }, requestId);
       } else {
-        emit(
+        this.emit(
           "completed",
           { success: false, error: "Tool not found" },
           requestId
@@ -6694,64 +6997,60 @@ ${userMessage}` : header;
       return;
     }
     if (action === "compact") {
-      triggerCompaction(state, config, {
+      triggerCompaction(this.state, this.config, {
         onStart: () => {
-          sessionStats.compactionInProgress = true;
-          sessionStats.updatedAt = Date.now();
-          try {
-            writeFileSync(".remy-stats.json", JSON.stringify(sessionStats));
-          } catch {
-          }
+          this.sessionStats.compactionInProgress = true;
+          this.persistStats();
         },
         onSummariesReady: () => {
-          if (!running) {
-            applyPendingSummaries();
+          if (!this.running) {
+            this.applyPendingSummaries();
           }
-          emit("compaction_complete", {}, requestId);
-          emit("completed", { success: true }, requestId);
+          this.emit("compaction_complete", {}, requestId);
+          this.emit("completed", { success: true }, requestId);
         },
         onError: (error) => {
-          emit("compaction_complete", { error }, requestId);
-          emit("completed", { success: false, error }, requestId);
+          this.emit("compaction_complete", { error }, requestId);
+          this.emit("completed", { success: false, error }, requestId);
         },
         onFinally: () => {
-          sessionStats.compactionInProgress = false;
-          sessionStats.lastContextSize = 0;
-          sessionStats.messageCount = state.messages.length;
-          sessionStats.updatedAt = Date.now();
-          try {
-            writeFileSync(".remy-stats.json", JSON.stringify(sessionStats));
-          } catch {
-          }
+          this.sessionStats.compactionInProgress = false;
+          this.sessionStats.lastContextSize = 0;
+          this.sessionStats.messageCount = this.state.messages.length;
+          this.persistStats();
         }
       });
       return;
     }
     if (action === "message") {
-      await handleMessage(parsed, requestId);
+      await this.handleMessage(parsed, requestId);
       return;
     }
-    emit("error", { error: `Unknown action: ${action}` }, requestId);
-    emit(
+    if (action === "resume") {
+      if (this.running) {
+        this.emit(
+          "completed",
+          { success: false, error: "already running" },
+          requestId
+        );
+        return;
+      }
+      if (this.queue.length === 0) {
+        this.emit("completed", { success: true }, requestId);
+        return;
+      }
+      this.emit("completed", { success: true }, requestId);
+      await this.resumeQueue();
+      return;
+    }
+    this.emit("error", { error: `Unknown action: ${action}` }, requestId);
+    this.emit(
       "completed",
       { success: false, error: `Unknown action: ${action}` },
       requestId
     );
-  });
-  rl.on("close", () => {
-    emit("stopping");
-    emit("stopped");
-    process.exit(0);
-  });
-  function shutdown() {
-    emit("stopping");
-    emit("stopped");
-    process.exit(0);
-  }
-  process.on("SIGTERM", shutdown);
-  process.on("SIGINT", shutdown);
-  emit("ready");
-}
+  };
+};
 export {
-  startHeadless
+  HeadlessSession
 };