@maintainer-pro/ai-cli 0.1.4 → 0.1.6

package/dist/index.js

@@ -2,6 +2,43 @@
 import { execa as execa2 } from "execa";
 
 // src/prompt.ts
+var PROMPT_SECTION = {
+  system: { begin: "<<<SYSTEM_BEGIN>>>", end: "<<<SYSTEM_END>>>" },
+  clientContext: {
+    begin: "<<<CLIENT_CONTEXT_BEGIN>>>",
+    end: "<<<CLIENT_CONTEXT_END>>>"
+  },
+  priorConversations: {
+    begin: "<<<PRIOR_CONVERSATIONS_BEGIN>>>",
+    end: "<<<PRIOR_CONVERSATIONS_END>>>"
+  },
+  parentChain: {
+    begin: "<<<PARENT_CHAIN_BEGIN>>>",
+    end: "<<<PARENT_CHAIN_END>>>"
+  },
+  history: {
+    begin: "<<<CONVERSATION_HISTORY_BEGIN>>>",
+    end: "<<<CONVERSATION_HISTORY_END>>>"
+  },
+  attachments: {
+    begin: "<<<ATTACHMENTS_BEGIN>>>",
+    end: "<<<ATTACHMENTS_END>>>"
+  },
+  currentRequest: {
+    begin: "<<<CURRENT_REQUEST_BEGIN>>>",
+    end: "<<<CURRENT_REQUEST_END>>>"
+  }
+};
+function wrapSection(tag, body, title) {
+  const trimmed = body.trim();
+  if (!trimmed) return "";
+  const header = title ? `${tag.begin} ${title}` : tag.begin;
+  return `${header}
+${trimmed}
+${tag.end}
+
+`;
+}
 function buildConversationPrompt(messages) {
   if (messages.length === 0) return "";
   const lines = messages.map(
@@ -43,50 +80,67 @@ function splitMessages(messages) {
   const history = latestUserIndex > 0 ? messages.slice(0, latestUserIndex) : [];
   return { request, history };
 }
-function buildUserFacingPrompt(systemPrompt, messages, context, attachmentPaths, priorConversationsContext, technical) {
+function buildUserFacingPrompt(systemPrompt, messages, context, attachmentPaths, priorConversationsContext, technical, parentChainContext) {
   const { request, history } = splitMessages(messages);
-  const historyBlock = history.length > 0 ? `Conversation so far:
-${buildConversationPrompt(history)}
-
-` : "";
-  const contextBlock = formatClientContext(context);
-  const contextSection = contextBlock ? `${contextBlock}
-
-` : "";
-  const systemSection = systemPrompt ? `${systemPrompt}
-
-` : "";
-  const priorSection = priorConversationsContext?.trim() ? `${priorConversationsContext.trim()}
-
-` : "";
-  const attachmentsSection = attachmentPaths && attachmentPaths.length > 0 ? `Screenshots / images attached by the user (open and inspect these image files):
-${attachmentPaths.map((p) => `- ${p}`).join("\n")}
-
-` : "";
+  const systemSection = wrapSection(
+    PROMPT_SECTION.system,
+    systemPrompt ?? "",
+    "instructions"
+  );
+  const contextSection = wrapSection(
+    PROMPT_SECTION.clientContext,
+    formatClientContext(context),
+    "live UI snapshot"
+  );
+  const priorSection = wrapSection(
+    PROMPT_SECTION.priorConversations,
+    priorConversationsContext ?? "",
+    "other chats (secondary)"
+  );
+  const parentSection = wrapSection(
+    PROMPT_SECTION.parentChain,
+    parentChainContext ?? "",
+    "reply-to parents \u2014 primary thread context"
+  );
+  const historySection = wrapSection(
+    PROMPT_SECTION.history,
+    history.length > 0 ? buildConversationPrompt(history) : "",
+    "earlier turns in this conversation"
+  );
+  const attachmentsSection = wrapSection(
+    PROMPT_SECTION.attachments,
+    attachmentPaths && attachmentPaths.length > 0 ? `Screenshots / images attached by the user (open and inspect these image files; they are stored under ~/.maintainer-pro for this project, not in the host app, and you are allowed to read them):
+${attachmentPaths.map((p) => `- ${p}`).join("\n")}` : "",
+    "user attachments"
+  );
+  const currentSection = wrapSection(
+    PROMPT_SECTION.currentRequest,
+    request || "(See the attached screenshot(s).)",
+    "answer this message"
+  );
   const closer = technical ? "Do the work now. Follow the requested output format exactly." : "Do the work now (or ask one short clarifying question if needed). Reply in English, non-technical and user-facing. If it's not resolving, offer a quick call.";
-  return `${systemSection}${contextSection}${priorSection}${historyBlock}${attachmentsSection}Current user request:
-${request || "(See the attached screenshot(s).)"}
-
-${closer}`;
+  return `${systemSection}${contextSection}${priorSection}${parentSection}${historySection}${attachmentsSection}${currentSection}${closer}`;
 }
-function buildCursorPrompt(systemPrompt, messages, context, attachmentPaths, priorConversationsContext, technical) {
+function buildCursorPrompt(systemPrompt, messages, context, attachmentPaths, priorConversationsContext, technical, parentChainContext) {
   return buildUserFacingPrompt(
     systemPrompt,
     messages,
     context,
     attachmentPaths,
     priorConversationsContext,
-    technical
+    technical,
+    parentChainContext
   );
 }
-function buildClaudeUserPrompt(messages, context, attachmentPaths, priorConversationsContext, technical) {
+function buildClaudeUserPrompt(messages, context, attachmentPaths, priorConversationsContext, technical, parentChainContext) {
   return buildUserFacingPrompt(
     null,
     messages,
     context,
     attachmentPaths,
     priorConversationsContext,
-    technical
+    technical,
+    parentChainContext
   );
 }
 
@@ -200,7 +254,8 @@ async function callClaudeCli(command, messages, context, options) {
     context,
     options.attachmentPaths,
     options.priorConversationsContext,
-    options.technical
+    options.technical,
+    options.parentChainContext
   );
   const resolved = resolveCliCommand("claude", command);
   const workspace = options.workspaceDir ?? process.env.AI_CLI_WORKSPACE ?? process.cwd();
@@ -240,7 +295,8 @@ async function callCursorCli(command, messages, context, options) {
     context,
     options.attachmentPaths,
     options.priorConversationsContext,
-    options.technical
+    options.technical,
+    options.parentChainContext
   );
   const resolved = resolveCliCommand("cursor", command);
   const workspace = options.workspaceDir ?? process.env.AI_CLI_WORKSPACE ?? process.cwd();
@@ -282,7 +338,8 @@ async function callAntigravityCli(command, messages, context, options) {
     context,
     options.attachmentPaths,
     options.priorConversationsContext,
-    options.technical
+    options.technical,
+    options.parentChainContext
   );
   const prompt = `You are operating as a coding agent with full permission to read and edit files in this workspace. Do not introduce yourself. Do not ask what you are. Execute the user's latest request now (edit files and/or emit runtime tool JSON as instructed).
 
@@ -323,8 +380,8 @@ async function resolveCommandPath(command) {
     }
     const result = await execa2("which", [command], { reject: false });
     if (result.exitCode !== 0) return null;
-    const path5 = result.stdout.trim().split(/\r?\n/)[0]?.trim();
-    return path5 || null;
+    const path9 = result.stdout.trim().split(/\r?\n/)[0]?.trim();
+    return path9 || null;
   } catch {
     return null;
   }
@@ -410,6 +467,51 @@ async function callAi(messages, context, options) {
   return provider.call(messages, context, options);
 }
 
+// src/parent-chain.ts
+function collectParentChain(rows, startId) {
+  if (!startId) return [];
+  const byId = new Map(rows.map((row) => [row.id, row]));
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = byId.get(startId);
+  while (current && !seen.has(current.id)) {
+    seen.add(current.id);
+    const content = String(current.content ?? "").trim();
+    if (content && current.provider !== "working") {
+      const role = current.role === "assistant" || current.role === "system" ? current.role : "user";
+      chain.unshift({
+        id: current.id,
+        role,
+        content,
+        ...current.senderName?.trim() ? { senderName: current.senderName.trim() } : {}
+      });
+    }
+    const nextId = current.parentMessageId?.trim();
+    current = nextId ? byId.get(nextId) : void 0;
+  }
+  return chain;
+}
+function parentChainForTurn(rows, currentMessageId, fallbackParentId) {
+  if (!currentMessageId && !fallbackParentId) return [];
+  const byId = new Map(rows.map((row) => [row.id, row]));
+  const current = currentMessageId ? byId.get(currentMessageId) : void 0;
+  const replyToId = current?.parentMessageId && String(current.parentMessageId).trim() || fallbackParentId && String(fallbackParentId).trim() || null;
+  return collectParentChain(rows, replyToId);
+}
+function formatParentChainContext(chain) {
+  if (chain.length === 0) return "";
+  const lines = [
+    "context: this message has parents hierarchy linked with it",
+    "Prefer this chain over unrelated queued or later messages when interpreting the current request.",
+    ""
+  ];
+  chain.forEach((entry, index) => {
+    const who = entry.senderName || (entry.role === "assistant" ? "Assistant" : entry.role === "system" ? "System" : "Human");
+    lines.push(`${index + 1}. [${who}] ${entry.content}`);
+  });
+  return lines.join("\n");
+}
+
 // src/system-prompt.ts
 function createDefaultSystemPrompt(input) {
   const files = input.relevantFilesHint ? `Key UI files (use internally only; never name them in your reply):
@@ -420,6 +522,14 @@ Only when the user wants to change live in-app data (not source code), return a
 ${input.runtimeToolsHint}
 
 Only use those runtime tools for live state. Never invent runtime tools.` : "";
+  const access = input.ignorePaths !== void 0 ? `
+
+## File access boundaries (mandatory)
+- You may only read or edit files inside the current project workspace directory.
+- Never read, write, move, or delete files outside that workspace.
+- Never touch paths that match this ignore list (relative to the workspace):
+${(input.ignorePaths ?? []).filter((p) => !p.startsWith("!")).length ? (input.ignorePaths ?? []).filter((p) => !p.startsWith("!")).map((p) => `- ${p}`).join("\n") : "- (none beyond staying inside the workspace)"}
+- If a request requires something outside the workspace or on the ignore list, refuse that part and explain you can only change allowed project files.` : "";
   return `You are a helpful product assistant for an app the user is looking at right now.
 
 ${input.productDescription}
@@ -440,6 +550,7 @@ Behind the scenes you can edit this repository and update live app data, but the
 ## When to edit the codebase
 Edit source files when the user asks to change labels, layout, styling, copy, or behavior in the app.
 ${files}
+${access}
 
 ${tools}
 
@@ -447,14 +558,257 @@ Do not refuse UI/label changes \u2014 implement them in source files.
 Answer the user's latest request directly \u2014 never reply with a generic greeting.`;
 }
 
-// src/http/attachments.ts
-import fs2 from "fs/promises";
+// src/access-policy.ts
 import path2 from "path";
+var DEFAULT_AI_IGNORE_PATHS = [
+  ".env",
+  ".env.*",
+  "**/.env",
+  "**/.env.*"
+];
+function parseIgnorePathsEnv(raw) {
+  if (!raw?.trim()) return [];
+  const trimmed = raw.trim();
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) {
+      return normalizeIgnorePaths(parsed.map(String));
+    }
+  } catch {
+  }
+  return normalizeIgnorePaths(trimmed.split(/[\n,]+/));
+}
+function normalizeIgnorePaths(paths) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of paths) {
+    const p = raw.trim().replace(/\\/g, "/");
+    if (!p || p.startsWith("/") || p.includes("..")) continue;
+    if (seen.has(p)) continue;
+    seen.add(p);
+    out.push(p);
+  }
+  return out;
+}
+function resolveIgnorePaths(partnerPaths) {
+  return normalizeIgnorePaths([
+    ...DEFAULT_AI_IGNORE_PATHS,
+    ...partnerPaths
+  ]);
+}
+function isInsideWorkspace(workspaceDir, targetPath) {
+  const root = path2.resolve(workspaceDir);
+  const target = path2.resolve(targetPath);
+  const rel = path2.relative(root, target);
+  return rel === "" || !rel.startsWith("..") && !path2.isAbsolute(rel);
+}
+function globToRegExp(pattern) {
+  let p = pattern.replace(/\\/g, "/");
+  if (p.endsWith("/")) p = `${p}**`;
+  let i = 0;
+  let out = "^";
+  while (i < p.length) {
+    if (p.startsWith("**/", i)) {
+      out += "(?:.*/)?";
+      i += 3;
+      continue;
+    }
+    if (p[i] === "*" && p[i + 1] !== "*") {
+      out += "[^/]*";
+      i += 1;
+      continue;
+    }
+    if (p.startsWith("**", i)) {
+      out += ".*";
+      i += 2;
+      continue;
+    }
+    if (p[i] === "?") {
+      out += "[^/]";
+      i += 1;
+      continue;
+    }
+    const ch = p[i];
+    if (/[.+^${}()|[\]\\]/.test(ch)) out += `\\${ch}`;
+    else out += ch;
+    i += 1;
+  }
+  out += "$";
+  return new RegExp(out, "i");
+}
+function isIgnoredRelative(relativePath, patterns) {
+  const rel = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (!rel) return false;
+  return patterns.some((pattern) => {
+    const re = globToRegExp(pattern);
+    if (re.test(rel)) return true;
+    if (!pattern.includes("*") && !pattern.endsWith("/")) {
+      return rel === pattern || rel.startsWith(`${pattern}/`);
+    }
+    return false;
+  });
+}
+function isPathAllowed(workspaceDir, targetPath, ignorePaths) {
+  if (!isInsideWorkspace(workspaceDir, targetPath)) return false;
+  const rel = path2.relative(path2.resolve(workspaceDir), path2.resolve(targetPath));
+  return !isIgnoredRelative(rel, ignorePaths);
+}
+function formatAccessPolicyPromptSection(input) {
+  const ignores = input.ignorePaths.filter((p) => !p.startsWith("!")).length ? input.ignorePaths.filter((p) => !p.startsWith("!")).map((p) => `- ${p}`).join("\n") : "- (none beyond staying inside the workspace)";
+  return `## File access boundaries (mandatory)
+- You may only read or edit files inside the current project workspace directory.
+- Never write, move, or delete files outside that workspace.
+- You may read screenshot files listed in the attachments section (those live in the Maintainer Pro data folder, not in the project).
+- Never touch paths that match this ignore list (relative to the workspace):
+${ignores}
+- If a request requires something outside the workspace or on the ignore list, refuse that part and explain you can only change allowed project files.`;
+}
+var ACCESS_IGNORE_BEGIN = "# maintainer-pro:access-begin";
+var ACCESS_IGNORE_END = "# maintainer-pro:access-end";
+function renderManagedIgnoreBlock(ignorePaths) {
+  const lines = [
+    ACCESS_IGNORE_BEGIN,
+    "# Managed by Maintainer Pro \u2014 do not edit this block by hand.",
+    ...ignorePaths,
+    ACCESS_IGNORE_END
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function upsertManagedIgnoreFile(existing, ignorePaths) {
+  const block = renderManagedIgnoreBlock(ignorePaths);
+  const begin = existing.indexOf(ACCESS_IGNORE_BEGIN);
+  const end = existing.indexOf(ACCESS_IGNORE_END);
+  if (begin >= 0 && end > begin) {
+    const afterEnd = end + ACCESS_IGNORE_END.length;
+    const before = existing.slice(0, begin).replace(/\s+$/, "");
+    let after = existing.slice(afterEnd).replace(/^\r?\n/, "");
+    const parts = [before, block.trimEnd(), after.trimStart()].filter(
+      (s) => s.length > 0
+    );
+    return `${parts.join("\n\n")}
+`;
+  }
+  const trimmed = existing.replace(/\s+$/, "");
+  return trimmed ? `${trimmed}
+
+${block}` : block;
+}
+
+// src/http/handler.ts
+import { randomUUID } from "crypto";
+
+// src/log.ts
+import pino from "pino";
+function isDevMode() {
+  if (process.env.AI_DEV === "1" || process.env.AI_DEV === "true") return true;
+  const env = (process.env.NODE_ENV || process.env.AI_ENV || "").trim().toLowerCase();
+  return env === "development" || env === "dev" || env === "test";
+}
+function resolveLogLevel() {
+  const explicit = process.env.LOG_LEVEL?.trim() || process.env.AI_LOG_LEVEL?.trim();
+  if (explicit) return explicit;
+  return isDevMode() ? "debug" : "info";
+}
+function createLogger(name) {
+  const level = resolveLogLevel();
+  const pretty = process.env.LOG_PRETTY !== "0" && typeof process.stdout?.isTTY === "boolean" && process.stdout.isTTY;
+  if (pretty) {
+    return pino({
+      name,
+      level,
+      transport: {
+        target: "pino-pretty",
+        options: {
+          colorize: true,
+          translateTime: "HH:MM:ss",
+          ignore: "pid,hostname"
+        }
+      }
+    });
+  }
+  return pino({ name, level });
+}
+function createInfoLogger(name) {
+  const log = createLogger(name);
+  return (msg) => {
+    log.info(msg);
+  };
+}
+function previewText(text, max = 160) {
+  const t = String(text ?? "").replace(/\s+/g, " ").trim();
+  if (!t) return "";
+  return t.length <= max ? t : `${t.slice(0, max)}\u2026`;
+}
+
+// src/http/attachments.ts
+import fs3 from "fs/promises";
+import path4 from "path";
+
+// src/project-data.ts
+import { createHash } from "crypto";
+import fs2 from "fs";
+import os from "os";
+import path3 from "path";
+var MAINTAINER_PRO_HOME_DIR = ".maintainer-pro";
+var HOST_APPS_FILE = "apps.json";
+function maintainerProHome() {
+  const override = process.env.MAINTAINER_PRO_HOME?.trim();
+  if (override) return path3.resolve(override);
+  return path3.join(os.homedir(), MAINTAINER_PRO_HOME_DIR);
+}
+function projectIdForFolder(folder) {
+  const resolved = path3.resolve(folder || "");
+  const key = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  return createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+function sanitizeProjectId(id) {
+  return String(id || "").trim().replace(/[^\w.-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 80);
+}
+function resolveProjectDataDir(input) {
+  const override = String(input.dataDir || "").trim();
+  if (override) return path3.resolve(override);
+  const sandbox = sanitizeProjectId(String(input.sandboxId || ""));
+  const id = sandbox || projectIdForFolder(input.workspaceDir);
+  return path3.join(maintainerProHome(), "projects", id);
+}
+function projectUploadsDir(input) {
+  return path3.join(resolveProjectDataDir(input), "uploads");
+}
+function hostAppsCachePath(input) {
+  return path3.join(resolveProjectDataDir(input), HOST_APPS_FILE);
+}
+function ensureProjectDataDir(input) {
+  const dir = resolveProjectDataDir(input);
+  fs2.mkdirSync(dir, { recursive: true });
+  fs2.mkdirSync(path3.join(dir, "uploads"), { recursive: true });
+  try {
+    fs2.writeFileSync(
+      path3.join(dir, "workspace.json"),
+      `${JSON.stringify(
+        {
+          workspaceDir: path3.resolve(input.workspaceDir || ""),
+          sandboxId: input.sandboxId ? String(input.sandboxId) : null,
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        null,
+        2
+      )}
+`,
+      "utf8"
+    );
+  } catch {
+  }
+  return dir;
+}
+
+// src/http/attachments.ts
 var MAX_ATTACHMENTS = 5;
 var MAX_BYTES = 4 * 1024 * 1024;
 var ALLOWED = /* @__PURE__ */ new Set(["image/png", "image/jpeg", "image/jpg", "image/webp", "image/gif"]);
 function extForMime(mime) {
-  switch (mime) {
+  const normalized = mime.split(";")[0]?.trim().toLowerCase() || "";
+  switch (normalized) {
     case "image/jpeg":
     case "image/jpg":
       return ".jpg";
@@ -466,11 +820,31 @@ function extForMime(mime) {
       return ".png";
   }
 }
-async function saveChatAttachments(attachments, workspaceDir) {
+function attachmentIdFromRef(ref) {
+  const trimmed = String(ref || "").trim();
+  if (!trimmed) return null;
+  const m = /^maintainer-pro:\/\/(.+)$/i.exec(trimmed);
+  if (m?.[1]) return m[1];
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+    trimmed
+  )) {
+    return trimmed;
+  }
+  return null;
+}
+function uploadsRoot(input) {
+  ensureProjectDataDir(input);
+  return projectUploadsDir(input);
+}
+async function saveChatAttachments(attachments, workspaceDir, extra) {
   if (!attachments?.length) return [];
   const selected = attachments.slice(0, MAX_ATTACHMENTS);
-  const dir = path2.join(workspaceDir, ".maintainer-pro", "uploads");
-  await fs2.mkdir(dir, { recursive: true });
+  const loc = {
+    workspaceDir,
+    dataDir: extra?.dataDir,
+    sandboxId: extra?.sandboxId
+  };
+  const dir = uploadsRoot(loc);
   const paths = [];
   const stamp = Date.now();
   for (let i = 0; i < selected.length; i++) {
@@ -488,8 +862,11 @@ async function saveChatAttachments(attachments, workspaceDir) {
     }
     const safeBase = (item.name || `screenshot-${i + 1}`).replace(/[^\w.\-]+/g, "_").slice(0, 64);
     const fileName = `${stamp}-${i + 1}-${safeBase}${extForMime(mime)}`;
-    const filePath = path2.join(dir, fileName);
-    await fs2.writeFile(filePath, buffer);
+    const filePath = path4.resolve(dir, fileName);
+    if (!isInsideWorkspace(dir, filePath)) {
+      throw new Error("Attachment path escaped the project data folder");
+    }
+    await fs3.writeFile(filePath, buffer);
     paths.push(filePath);
   }
   return paths;
@@ -575,7 +952,7 @@ function createToolValidator(schemas) {
 
 // src/http/handler.ts
 var WORKING_PROVIDER = "working";
-async function setWorkingMessage(db, conversationId) {
+async function setWorkingMessage(db, conversationId, parentMessageId) {
   await db.ensureConversation(conversationId);
   await db.clearWorkingMessages?.(conversationId);
   await db.saveMessage({
@@ -583,9 +960,26 @@ async function setWorkingMessage(db, conversationId) {
     role: "assistant",
     content: "",
     provider: WORKING_PROVIDER,
-    senderType: "ai"
+    senderType: "ai",
+    parentMessageId: parentMessageId ?? void 0
   });
 }
+function savedMessageFields(result) {
+  if (!result || typeof result !== "object") return {};
+  const row = result;
+  const next = row.nextQueued && typeof row.nextQueued === "object" && typeof row.nextQueued.id === "string" ? {
+    id: row.nextQueued.id,
+    content: String(
+      row.nextQueued.content ?? ""
+    )
+  } : null;
+  return {
+    id: typeof row.id === "string" ? row.id : void 0,
+    queueStatus: typeof row.queueStatus === "string" || row.queueStatus === null ? row.queueStatus : void 0,
+    queuePosition: typeof row.queuePosition === "number" || row.queuePosition === null ? row.queuePosition : void 0,
+    nextQueued: next
+  };
+}
 var SHARED_CONVERSATION_ID = "shared";
 var conversationTurnSeq = /* @__PURE__ */ new Map();
 function beginConversationTurn(conversationId) {
@@ -620,14 +1014,18 @@ async function resolveSharedConversationId(request, options, bodyId) {
   return SHARED_CONVERSATION_ID;
 }
 function createChatHandler(options) {
+  const logger = options.logger ?? createLogger("ai-cli:chat");
   const validate = options.tools ? createToolValidator(options.tools) : null;
   const workspaceDir = options.workspaceDir ?? process.env.AI_CLI_WORKSPACE ?? process.cwd();
+  const dataDir = options.dataDir;
+  const sandboxId = options.sandboxId;
   const baseCallOptions = {
     systemPrompt: options.systemPrompt,
     workspaceDir,
     providerPreference: options.providerPreference,
     providers: options.providers
   };
+  logger.debug({ workspaceDir }, "chat handler ready");
   return {
     async GET(request) {
       try {
@@ -643,6 +1041,14 @@ function createChatHandler(options) {
         if (options.db?.listMessages) {
           messages = await options.db.listMessages(conversationId);
         }
+        logger.debug(
+          {
+            conversationId,
+            provider: provider.id,
+            messageCount: messages?.length ?? 0
+          },
+          "GET /api/chat"
+        );
         return Response.json({
           provider: provider.id,
           providerLabel: provider.label || providerLabel(provider.id),
@@ -650,6 +1056,7 @@ function createChatHandler(options) {
           messages: messages ?? []
         });
       } catch (err) {
+        logger.error({ err }, "GET /api/chat failed");
         const message = err instanceof Error ? err.message : "No AI CLI provider available";
         return Response.json(
           { error: message, provider: null },
@@ -659,7 +1066,9 @@ function createChatHandler(options) {
     },
     async POST(request) {
       let trackedConversationId;
+      let trackedParentUserMessageId;
       let trackedTurn = 0;
+      const startedAt = Date.now();
       try {
         const body = await request.json();
         const conversationId = await resolveSharedConversationId(
@@ -668,6 +1077,19 @@ function createChatHandler(options) {
           body.conversationId
         );
         trackedConversationId = conversationId;
+        logger.debug(
+          {
+            conversationId,
+            type: body.type ?? "turn",
+            skipPersistUser: Boolean(body.skipPersistUser),
+            userMessageId: body.userMessageId,
+            messageCount: body.messages?.length ?? 0,
+            attachmentCount: body.attachments?.length ?? 0,
+            queueStatus: body.queueStatus,
+            preview: previewText(body.userMessage || body.content)
+          },
+          "POST /api/chat"
+        );
         if (body.type === "working-clear") {
           if (!conversationId) {
             return Response.json(
@@ -692,11 +1114,54 @@ function createChatHandler(options) {
             await options.db.ensureConversation(conversationId);
             await options.db.saveMessage({
               conversationId,
+              id: body.messageId,
               role: "assistant",
               content,
               provider: "developer",
               senderType: "developer",
-              senderName: body.senderName?.trim() || void 0
+              senderName: body.senderName?.trim() || void 0,
+              parentMessageId: body.parentMessageId
+            });
+          }
+          return Response.json({ ok: true, conversationId });
+        }
+        if (body.type === "user") {
+          const content = body.content?.trim();
+          if (!conversationId || !content) {
+            return Response.json(
+              { error: "conversationId and content are required" },
+              { status: 400 }
+            );
+          }
+          if (options.db) {
+            await options.db.ensureConversation(conversationId);
+            let persistAttachmentPaths2 = [];
+            if (options.db.uploadAttachments && body.attachments?.length) {
+              const uploaded = await options.db.uploadAttachments(
+                conversationId,
+                body.attachments
+              );
+              persistAttachmentPaths2 = uploaded.refs;
+            }
+            const saved = await options.db.saveMessage({
+              conversationId,
+              id: body.messageId,
+              role: "user",
+              content,
+              attachmentPaths: persistAttachmentPaths2.length > 0 ? persistAttachmentPaths2 : void 0,
+              senderType: body.senderType === "client" ? "client" : void 0,
+              senderName: body.senderName?.trim() || void 0,
+              parentMessageId: body.parentMessageId,
+              intent: "queue",
+              queueStatus: body.queueStatus === "queued" || body.queueStatus === "working" ? body.queueStatus : void 0
+            });
+            const fields = savedMessageFields(saved);
+            return Response.json({
+              ok: true,
+              conversationId,
+              message: saved,
+              queueStatus: fields.queueStatus ?? null,
+              queuePosition: fields.queuePosition ?? null
             });
           }
           return Response.json({ ok: true, conversationId });
@@ -710,44 +1175,99 @@ function createChatHandler(options) {
         }
         let attachmentPaths = [];
         let persistAttachmentPaths = [];
-        if (options.db?.uploadAttachments) {
+        if (options.db?.uploadAttachments && attachments?.length) {
           const uploaded = await options.db.uploadAttachments(
             conversationId,
             attachments
           );
           attachmentPaths = uploaded.localPaths;
           persistAttachmentPaths = uploaded.refs;
-        } else {
+        } else if (attachments?.length) {
           attachmentPaths = await saveChatAttachments(
             attachments,
-            workspaceDir
+            workspaceDir,
+            { dataDir, sandboxId }
           );
           persistAttachmentPaths = attachmentPaths;
         }
+        const storedUserId = typeof body.userMessageId === "string" && body.userMessageId ? body.userMessageId : void 0;
+        if (!attachmentPaths.length && conversationId && options.db?.materializeMessageAttachments) {
+          attachmentPaths = await options.db.materializeMessageAttachments(
+            conversationId,
+            storedUserId,
+            workspaceDir
+          );
+        }
+        logger.debug(
+          {
+            conversationId,
+            userMessageId: storedUserId,
+            attachmentCount: attachmentPaths.length
+          },
+          "cli attachments"
+        );
         const turn = beginConversationTurn(conversationId ?? SHARED_CONVERSATION_ID);
         trackedTurn = turn;
         const signal = request.signal;
+        let parentUserMessageId = typeof body.userMessageId === "string" && body.userMessageId ? body.userMessageId : void 0;
+        trackedParentUserMessageId = parentUserMessageId;
         if (options.db && conversationId) {
           const latest = messages[messages.length - 1];
           const persistContent = body.userMessage?.trim() || (latest?.role === "user" ? latest.content : "");
-          if (persistContent) {
+          if (persistContent && !body.skipPersistUser && !parentUserMessageId) {
             await options.db.ensureConversation(conversationId);
-            await options.db.saveMessage({
+            const saved = await options.db.saveMessage({
               conversationId,
               role: "user",
               content: persistContent,
               attachmentPaths: persistAttachmentPaths.length > 0 ? persistAttachmentPaths : void 0,
               senderType: body.senderType === "client" ? "client" : void 0,
-              senderName: body.senderName?.trim() || void 0
+              senderName: body.senderName?.trim() || void 0,
+              intent: "run"
             });
+            parentUserMessageId = savedMessageFields(saved).id ?? parentUserMessageId;
+            trackedParentUserMessageId = parentUserMessageId;
+          }
+          if (!body.skipPersistUser) {
+            await setWorkingMessage(
+              options.db,
+              conversationId,
+              parentUserMessageId
+            );
           }
-          await setWorkingMessage(options.db, conversationId);
         }
         const latestUser = [...messages].reverse().find((m) => m.role === "user");
         const priorConversationsContext = options.db ? await buildPriorConversationsContext(options.db, {
           excludeConversationId: conversationId,
           currentRequest: latestUser?.content ?? ""
         }) : "";
+        let parentChainContext = "";
+        if (options.db?.listMessages && conversationId) {
+          const stored = await options.db.listMessages(conversationId);
+          const chain = parentChainForTurn(
+            stored.map((row) => ({
+              id: row.id,
+              role: row.role,
+              content: row.content,
+              parentMessageId: row.parentMessageId,
+              senderName: row.senderName,
+              provider: row.provider
+            })),
+            parentUserMessageId,
+            body.parentMessageId
+          );
+          parentChainContext = formatParentChainContext(chain);
+          if (parentChainContext) {
+            logger.debug(
+              {
+                conversationId,
+                parentUserMessageId,
+                chainLength: chain.length
+              },
+              "parent chain context"
+            );
+          }
+        }
         if (!isActiveConversationTurn(
           conversationId ?? SHARED_CONVERSATION_ID,
           turn
@@ -758,23 +1278,59 @@ function createChatHandler(options) {
           });
         }
         if (signal.aborted) {
-          if (options.db?.clearWorkingMessages && conversationId) {
-            await options.db.clearWorkingMessages(conversationId);
+          logger.debug({ conversationId, turn }, "aborted before AI");
+          if (conversationId && options.db) {
+            if (options.db.releaseWorkingTurn) {
+              await options.db.releaseWorkingTurn(
+                conversationId,
+                parentUserMessageId
+              );
+            } else {
+              await options.db.clearWorkingMessages?.(conversationId);
+            }
           }
           return Response.json({
             superseded: true,
             conversationId: conversationId ?? null
           });
         }
+        logger.debug(
+          {
+            conversationId,
+            turn,
+            parentUserMessageId,
+            historyLength: messages.length,
+            attachmentCount: attachmentPaths.length,
+            hasParentChain: Boolean(parentChainContext),
+            preview: previewText(
+              [...messages].reverse().find((m) => m.role === "user")?.content
+            )
+          },
+          "calling AI provider"
+        );
+        const aiStarted = Date.now();
         const aiResponse = await callAi(messages, context, {
           ...baseCallOptions,
           attachmentPaths,
-          priorConversationsContext: priorConversationsContext || void 0
+          priorConversationsContext: priorConversationsContext || void 0,
+          parentChainContext: parentChainContext || void 0
         });
+        logger.debug(
+          {
+            conversationId,
+            turn,
+            provider: aiResponse.provider,
+            toolCalls: aiResponse.toolCalls.length,
+            ms: Date.now() - aiStarted,
+            preview: previewText(aiResponse.text)
+          },
+          "AI provider returned"
+        );
         if (!isActiveConversationTurn(
           conversationId ?? SHARED_CONVERSATION_ID,
           turn
         )) {
+          logger.debug({ conversationId, turn }, "superseded after AI");
           return Response.json({
             superseded: true,
             conversationId: conversationId ?? null
@@ -782,38 +1338,108 @@ function createChatHandler(options) {
         }
         const validatedToolCalls = validate ? aiResponse.toolCalls.filter((tc) => validate(tc).valid) : aiResponse.toolCalls;
         if (options.onToolCalls && validatedToolCalls.length > 0) {
+          logger.debug(
+            { conversationId, count: validatedToolCalls.length },
+            "applying tool calls"
+          );
           await options.onToolCalls(validatedToolCalls, context);
         }
+        let nextQueued = null;
+        const assistantMessageId = typeof body.assistantMessageId === "string" && body.assistantMessageId ? body.assistantMessageId : randomUUID();
+        let replyId = assistantMessageId;
         if (options.db && conversationId) {
           await options.db.ensureConversation(conversationId);
-          await options.db.clearWorkingMessages?.(conversationId);
-          await options.db.saveMessage({
+          const savedReply = await options.db.saveMessage({
             conversationId,
+            id: assistantMessageId,
             role: "assistant",
             content: aiResponse.text,
             provider: aiResponse.provider,
-            senderType: "ai"
+            senderType: "ai",
+            parentMessageId: parentUserMessageId
           });
+          replyId = savedMessageFields(savedReply).id ?? assistantMessageId;
+          if (options.db.releaseWorkingTurn) {
+            let released = void 0;
+            for (let attempt = 0; attempt < 3; attempt++) {
+              try {
+                released = await options.db.releaseWorkingTurn(
+                  conversationId,
+                  parentUserMessageId
+                );
+                break;
+              } catch (err) {
+                logger.warn(
+                  { err, conversationId, parentUserMessageId, attempt },
+                  "releaseWorkingTurn failed; retrying"
+                );
+                if (attempt === 2) throw err;
+                await new Promise((r) => setTimeout(r, 250 * (attempt + 1)));
+              }
+            }
+            nextQueued = released && typeof released === "object" && released.nextQueued && typeof released.nextQueued.id === "string" ? {
+              id: released.nextQueued.id,
+              content: String(released.nextQueued.content ?? "")
+            } : null;
+            logger.debug(
+              { conversationId, parentUserMessageId, nextQueued: nextQueued?.id },
+              "released working turn"
+            );
+          } else {
+            await options.db.clearWorkingMessages?.(conversationId);
+            nextQueued = savedMessageFields(savedReply).nextQueued ?? null;
+          }
           if (validatedToolCalls.length > 0) {
             await options.db.saveToolEvents?.(
               conversationId,
               validatedToolCalls
             );
           }
+          logger.debug(
+            {
+              conversationId,
+              replyId,
+              nextQueued: nextQueued?.id
+            },
+            "persisted AI reply"
+          );
         }
+        logger.debug(
+          { conversationId, turn, ms: Date.now() - startedAt },
+          "POST /api/chat done"
+        );
         return Response.json({
           text: aiResponse.text,
           toolCalls: validatedToolCalls,
           provider: aiResponse.provider,
           providerLabel: providerLabel(aiResponse.provider),
-          conversationId: conversationId ?? null
+          conversationId: conversationId ?? null,
+          messageId: replyId,
+          nextQueued,
+          parentMessageId: parentUserMessageId ?? null
         });
       } catch (err) {
         console.error("Chat API error:", err);
-        if (trackedConversationId && options.db?.clearWorkingMessages && isActiveConversationTurn(trackedConversationId, trackedTurn)) {
-          await options.db.clearWorkingMessages(trackedConversationId).catch(
-            () => void 0
-          );
+        logger.error(
+          {
+            err,
+            conversationId: trackedConversationId,
+            turn: trackedTurn,
+            ms: Date.now() - startedAt
+          },
+          "POST /api/chat failed"
+        );
+        if (trackedConversationId && options.db && isActiveConversationTurn(trackedConversationId, trackedTurn)) {
+          if (options.db.releaseWorkingTurn) {
+            await options.db.releaseWorkingTurn(
+              trackedConversationId,
+              trackedParentUserMessageId
+            ).catch(() => void 0);
+          } else {
+            await options.db.clearWorkingMessages?.(trackedConversationId).catch(
+              () => void 0
+            );
+          }
         }
         return Response.json(
           {
@@ -833,12 +1459,17 @@ function toNextRoute(handlers) {
 }
 
 // src/http/local-store.ts
-import fs3 from "fs/promises";
-import path3 from "path";
-import { randomUUID } from "crypto";
+import fs4 from "fs/promises";
+import path5 from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+function userHasAiReply(rows, workingId) {
+  return rows.some(
+    (m) => m.role === "assistant" && m.parentMessageId === workingId && m.provider !== "working" && Boolean(m.content?.trim())
+  );
+}
 async function readConversation(filePath) {
   try {
-    const raw = await fs3.readFile(filePath, "utf8");
+    const raw = await fs4.readFile(filePath, "utf8");
     return JSON.parse(raw);
   } catch (err) {
     if (err.code === "ENOENT") return null;
@@ -846,11 +1477,11 @@ async function readConversation(filePath) {
   }
 }
 async function writeConversation(filePath, data) {
-  await fs3.mkdir(path3.dirname(filePath), { recursive: true });
-  await fs3.writeFile(filePath, JSON.stringify(data, null, 2), "utf8");
+  await fs4.mkdir(path5.dirname(filePath), { recursive: true });
+  await fs4.writeFile(filePath, JSON.stringify(data, null, 2), "utf8");
 }
 function createLocalDirectoryStore(baseDir) {
-  const fileFor = (id) => path3.join(baseDir, `${id}.json`);
+  const fileFor = (id) => path5.join(baseDir, `${id}.json`);
   return {
     async ensureConversation(id) {
       const existing = await readConversation(fileFor(id));
@@ -868,21 +1499,273 @@ function createLocalDirectoryStore(baseDir) {
         updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
         messages: []
       };
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const isClientUser = input.role === "user" && input.senderType !== "developer" && input.provider !== "developer";
+      const isWorking = input.provider === "working";
+      const isAi = input.role === "assistant" && input.provider !== "working" && input.senderType !== "developer" && input.provider !== "developer";
+      const busy = existing.messages.some((m) => m.queueStatus === "working");
+      const makeWorking = (parentMessageId) => ({
+        id: randomUUID2(),
+        conversationId: input.conversationId,
+        role: "assistant",
+        content: "",
+        provider: "working",
+        createdAt: now,
+        senderType: "ai",
+        parentMessageId
+      });
+      const promoteNext = () => {
+        const waiting = existing.messages.filter((m) => m.queueStatus === "queued").sort(
+          (a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)
+        );
+        const next = waiting[0];
+        if (!next) return null;
+        next.queueStatus = "working";
+        next.queuePosition = null;
+        existing.messages.push(makeWorking(next.id));
+        return next;
+      };
+      if (isClientUser) {
+        if (input.intent === "run") {
+          for (const row of existing.messages) {
+            if (row.queueStatus === "working") {
+              row.queueStatus = null;
+              row.queuePosition = null;
+            }
+          }
+          existing.messages = existing.messages.filter(
+            (m) => m.provider !== "working"
+          );
+        }
+        const queueStatus = input.intent === "run" ? "working" : busy ? "queued" : "working";
+        const existingById2 = input.id ? existing.messages.find((m) => m.id === input.id) : void 0;
+        if (existingById2) {
+          return { ...existingById2, nextQueued: null };
+        }
+        const message2 = {
+          id: input.id ?? randomUUID2(),
+          conversationId: input.conversationId,
+          role: input.role,
+          content: input.content,
+          provider: input.provider ?? null,
+          createdAt: now,
+          attachmentPaths: input.attachmentPaths,
+          senderType: input.senderType ?? null,
+          senderName: input.senderName ?? null,
+          parentMessageId: input.parentMessageId ?? null,
+          queueStatus,
+          queuePosition: null
+        };
+        existing.messages.push(message2);
+        existing.updatedAt = now;
+        await writeConversation(filePath, existing);
+        return { ...message2, nextQueued: null };
+      }
+      if (isWorking) {
+        existing.messages = existing.messages.filter(
+          (m) => m.provider !== "working"
+        );
+        if (input.parentMessageId) {
+          const parent = existing.messages.find(
+            (m) => m.id === input.parentMessageId
+          );
+          if (parent && parent.queueStatus !== "working") {
+            parent.queueStatus = "working";
+            parent.queuePosition = null;
+          }
+        }
+        const message2 = {
+          id: input.id ?? randomUUID2(),
+          conversationId: input.conversationId,
+          role: "assistant",
+          content: "",
+          provider: "working",
+          createdAt: now,
+          senderType: "ai",
+          parentMessageId: input.parentMessageId ?? null
+        };
+        existing.messages.push(message2);
+        existing.updatedAt = now;
+        await writeConversation(filePath, existing);
+        return { ...message2, nextQueued: null };
+      }
+      const existingById = input.id ? existing.messages.find((m) => m.id === input.id) : void 0;
+      if (existingById) {
+        return { ...existingById, nextQueued: null };
+      }
       const message = {
-        id: randomUUID(),
+        id: input.id ?? randomUUID2(),
         conversationId: input.conversationId,
         role: input.role,
         content: input.content,
         provider: input.provider ?? null,
-        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        createdAt: now,
         attachmentPaths: input.attachmentPaths,
         senderType: input.senderType ?? null,
-        senderName: input.senderName ?? null
+        senderName: input.senderName ?? null,
+        parentMessageId: input.parentMessageId ?? null
       };
       existing.messages.push(message);
-      existing.updatedAt = message.createdAt;
+      let nextQueued = null;
+      if (isAi) {
+        existing.messages = existing.messages.filter(
+          (m) => m.provider !== "working"
+        );
+        if (input.parentMessageId) {
+          const parent = existing.messages.find(
+            (m) => m.id === input.parentMessageId
+          );
+          if (parent) {
+            parent.queueStatus = null;
+            parent.queuePosition = null;
+          }
+        } else {
+          for (const row of existing.messages) {
+            if (row.queueStatus === "working") {
+              row.queueStatus = null;
+              row.queuePosition = null;
+            }
+          }
+        }
+        nextQueued = promoteNext();
+      }
+      existing.updatedAt = now;
+      await writeConversation(filePath, existing);
+      return {
+        ...message,
+        nextQueued: nextQueued ? { id: nextQueued.id, content: nextQueued.content } : null
+      };
+    },
+    async recoverQueue(conversationId) {
+      const filePath = fileFor(conversationId);
+      const existing = await readConversation(filePath);
+      if (!existing) {
+        return {
+          action: "noop",
+          workingId: null,
+          promotedId: null,
+          nextQueued: null
+        };
+      }
+      const working = existing.messages.find(
+        (m) => m.role === "user" && m.queueStatus === "working"
+      );
+      if (working) {
+        if (userHasAiReply(existing.messages, working.id)) {
+          existing.messages = existing.messages.filter(
+            (m) => m.provider !== "working"
+          );
+          working.queueStatus = null;
+          working.queuePosition = null;
+          const waiting2 = existing.messages.filter((m) => m.queueStatus === "queued").sort(
+            (a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)
+          );
+          const next2 = waiting2[0] ?? null;
+          if (next2) {
+            next2.queueStatus = "working";
+            next2.queuePosition = null;
+            existing.messages.push({
+              id: randomUUID2(),
+              conversationId,
+              role: "assistant",
+              content: "",
+              provider: "working",
+              createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+              senderType: "ai",
+              parentMessageId: next2.id
+            });
+          }
+          existing.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+          await writeConversation(filePath, existing);
+          return {
+            action: "completed_and_promoted",
+            workingId: working.id,
+            promotedId: next2?.id ?? null,
+            nextQueued: next2 ? { id: next2.id, content: next2.content } : null
+          };
+        }
+        return {
+          action: "redispatched_working",
+          workingId: working.id,
+          promotedId: null,
+          nextQueued: null
+        };
+      }
+      const waiting = existing.messages.filter((m) => m.queueStatus === "queued").sort(
+        (a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)
+      );
+      const next = waiting[0] ?? null;
+      if (!next) {
+        return {
+          action: "noop",
+          workingId: null,
+          promotedId: null,
+          nextQueued: null
+        };
+      }
+      next.queueStatus = "working";
+      next.queuePosition = null;
+      existing.messages.push({
+        id: randomUUID2(),
+        conversationId,
+        role: "assistant",
+        content: "",
+        provider: "working",
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        senderType: "ai",
+        parentMessageId: next.id
+      });
+      existing.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      await writeConversation(filePath, existing);
+      return {
+        action: "promoted_queued",
+        workingId: null,
+        promotedId: next.id,
+        nextQueued: { id: next.id, content: next.content }
+      };
+    },
+    async releaseWorkingTurn(conversationId, parentMessageId) {
+      const filePath = fileFor(conversationId);
+      const existing = await readConversation(filePath);
+      if (!existing) return { nextQueued: null };
+      existing.messages = existing.messages.filter(
+        (m) => m.provider !== "working"
+      );
+      if (parentMessageId) {
+        const parent = existing.messages.find((m) => m.id === parentMessageId);
+        if (parent) {
+          parent.queueStatus = null;
+          parent.queuePosition = null;
+        }
+      } else {
+        for (const row of existing.messages) {
+          if (row.queueStatus === "working") {
+            row.queueStatus = null;
+            row.queuePosition = null;
+          }
+        }
+      }
+      const waiting = existing.messages.filter((m) => m.queueStatus === "queued").sort(
+        (a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)
+      );
+      const next = waiting[0] ?? null;
+      if (next) {
+        next.queueStatus = "working";
+        next.queuePosition = null;
+        existing.messages.push({
+          id: randomUUID2(),
+          conversationId,
+          role: "assistant",
+          content: "",
+          provider: "working",
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          senderType: "ai",
+          parentMessageId: next.id
+        });
+      }
+      existing.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
       await writeConversation(filePath, existing);
-      return message;
+      return next ? { nextQueued: { id: next.id, content: next.content } } : { nextQueued: null };
     },
     async clearWorkingMessages(conversationId) {
       const filePath = fileFor(conversationId);
@@ -899,12 +1782,12 @@ function createLocalDirectoryStore(baseDir) {
       return existing?.messages ?? [];
     },
     async listConversations() {
-      await fs3.mkdir(baseDir, { recursive: true });
-      const entries = await fs3.readdir(baseDir);
+      await fs4.mkdir(baseDir, { recursive: true });
+      const entries = await fs4.readdir(baseDir);
       const conversations = [];
       for (const entry of entries) {
         if (!entry.endsWith(".json")) continue;
-        const filePath = path3.join(baseDir, entry);
+        const filePath = path5.join(baseDir, entry);
         const existing = await readConversation(filePath);
         if (!existing?.id) continue;
         conversations.push({
@@ -921,7 +1804,7 @@ function createLocalDirectoryStore(baseDir) {
       if (events.length === 0) return;
       const existing = await readConversation(fileFor(conversationId));
       if (!existing) return;
-      const toolFile = path3.join(baseDir, `${conversationId}.tools.jsonl`);
+      const toolFile = path5.join(baseDir, `${conversationId}.tools.jsonl`);
       const lines = events.map(
         (e) => JSON.stringify({
           conversationId,
@@ -929,33 +1812,386 @@ function createLocalDirectoryStore(baseDir) {
           createdAt: (/* @__PURE__ */ new Date()).toISOString()
         })
       ).join("\n");
-      await fs3.appendFile(toolFile, `${lines}
+      await fs4.appendFile(toolFile, `${lines}
 `, "utf8");
     }
   };
 }
 
 // src/http/maintainer-pro-store.ts
-import fs4 from "fs/promises";
-import os from "os";
-import path4 from "path";
-async function mpFetch(baseUrl, apiKey, pathName, init, fetchImpl) {
-  const url = `${baseUrl.replace(/\/$/, "")}${pathName}`;
-  const res = await fetchImpl(url, {
-    ...init,
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      "Content-Type": "application/json",
-      ...init?.headers ?? {}
-    }
-  });
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error(
-      `Maintainer Pro ${pathName} failed (${res.status}): ${text || res.statusText}`
-    );
-  }
-  const contentType = res.headers.get("content-type") ?? "";
+import fs5 from "fs/promises";
+import path6 from "path";
+
+// src/http/synced-store.ts
+function userHasAiReply2(rows, workingId) {
+  return rows.some(
+    (row) => row.role === "assistant" && row.parentMessageId === workingId && row.provider !== "working" && row.senderType !== "developer" && Boolean(row.content?.trim())
+  );
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function toWsUrl(baseUrl, apiKey) {
+  const u = new URL(`${baseUrl.replace(/\/$/, "")}/api/v1/ws`);
+  u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+  u.searchParams.set("apiKey", apiKey);
+  return u.toString();
+}
+function asCachedMessage(raw) {
+  const id = typeof raw.id === "string" ? raw.id : "";
+  const role = typeof raw.role === "string" ? raw.role : "";
+  if (!id || !role) return null;
+  return {
+    id,
+    role,
+    content: typeof raw.content === "string" ? raw.content : "",
+    provider: typeof raw.provider === "string" ? raw.provider : null,
+    createdAt: typeof raw.createdAt === "string" ? raw.createdAt : void 0,
+    attachmentPaths: Array.isArray(raw.attachmentPaths) ? raw.attachmentPaths.filter((p) => typeof p === "string") : Array.isArray(raw.attachmentIds) ? raw.attachmentIds.filter((id2) => typeof id2 === "string").map((id2) => `maintainer-pro://${id2}`) : void 0,
+    senderType: raw.senderType === "client" || raw.senderType === "developer" || raw.senderType === "ai" ? raw.senderType : null,
+    senderName: typeof raw.senderName === "string" ? raw.senderName : null,
+    parentMessageId: typeof raw.parentMessageId === "string" ? raw.parentMessageId : null,
+    queueStatus: raw.queueStatus === "working" || raw.queueStatus === "queued" ? raw.queueStatus : raw.queueStatus === null ? null : void 0,
+    queuePosition: typeof raw.queuePosition === "number" ? raw.queuePosition : null
+  };
+}
+function cloneMessages(messages) {
+  return messages.map((m) => ({ ...m }));
+}
+function createSyncedChatStore(options) {
+  const { remote, maintainerProUrl, apiKey, onWorkingTurn } = options;
+  const logger = options.logger ?? createLogger("ai-cli");
+  const info = (msg) => {
+    if (options.log) options.log(msg);
+    else logger.info(msg);
+  };
+  const conversations = /* @__PURE__ */ new Map();
+  const inflightRefresh = /* @__PURE__ */ new Map();
+  let stopped = false;
+  let socket = null;
+  let reconnectAttempt = 0;
+  let reconnectTimer = null;
+  let pingTimer = null;
+  const stats = () => {
+    let messages = 0;
+    for (const conv of conversations.values()) messages += conv.messages.length;
+    return { conversations: conversations.size, messages };
+  };
+  const putConversation = (id, messages, updatedAt = nowIso()) => {
+    conversations.set(id, { id, updatedAt, messages: cloneMessages(messages) });
+  };
+  const refreshConversation = (id) => {
+    const existing = inflightRefresh.get(id);
+    if (existing) return existing;
+    const pending = (async () => {
+      const messages = remote.listMessages ? await remote.listMessages(id) : [];
+      putConversation(id, messages);
+      return cloneMessages(messages);
+    })().finally(() => {
+      inflightRefresh.delete(id);
+    });
+    inflightRefresh.set(id, pending);
+    return pending;
+  };
+  const loadSnapshot = async () => {
+    if (remote.listSnapshot) {
+      try {
+        return await remote.listSnapshot();
+      } catch {
+      }
+    }
+    if (!remote.listConversations || !remote.listMessages) return [];
+    const summaries = await remote.listConversations();
+    const loaded = [];
+    for (const row of summaries) {
+      loaded.push({
+        id: row.id,
+        updatedAt: row.updatedAt,
+        messages: await remote.listMessages(row.id)
+      });
+    }
+    return loaded;
+  };
+  const hydrate = async () => {
+    const snapshot = await loadSnapshot();
+    conversations.clear();
+    for (const row of snapshot) {
+      putConversation(row.id, row.messages, row.updatedAt);
+    }
+    const next = stats();
+    info(
+      `cache hydrated (${next.conversations} conversations, ${next.messages} messages)`
+    );
+    for (const conv of conversations.values()) {
+      const working = conv.messages.find(
+        (row) => row.role === "user" && row.queueStatus === "working" && row.senderType !== "developer"
+      );
+      if (!working) continue;
+      if (!userHasAiReply2(conv.messages, working.id)) {
+        logger.debug(
+          { conversationId: conv.id, messageId: working.id },
+          "resume working turn"
+        );
+        onWorkingTurn?.({ conversationId: conv.id, message: working });
+      }
+    }
+    return next;
+  };
+  const upsertMessage = (conversationId, message) => {
+    const conv = conversations.get(conversationId) ?? {
+      id: conversationId,
+      updatedAt: nowIso(),
+      messages: []
+    };
+    const index = conv.messages.findIndex((row) => row.id === message.id);
+    const wasWorking = index >= 0 && conv.messages[index]?.queueStatus === "working";
+    if (index >= 0) {
+      conv.messages[index] = { ...conv.messages[index], ...message };
+    } else {
+      conv.messages.push(message);
+    }
+    conv.updatedAt = nowIso();
+    conversations.set(conversationId, conv);
+    const becameWorking = message.role === "user" && message.queueStatus === "working" && message.senderType !== "developer" && !wasWorking;
+    if (becameWorking) {
+      logger.debug(
+        { conversationId, messageId: message.id },
+        "working turn"
+      );
+      onWorkingTurn?.({ conversationId, message });
+    }
+  };
+  const deleteMessages = (conversationId, ids) => {
+    const conv = conversations.get(conversationId);
+    if (!conv || ids.length === 0) return;
+    const drop = new Set(ids);
+    conv.messages = conv.messages.filter((row) => !drop.has(row.id));
+    conv.updatedAt = nowIso();
+  };
+  const applyEvent = (msg) => {
+    const externalId = typeof msg.externalId === "string" && msg.externalId ? msg.externalId : typeof msg.conversationId === "string" ? msg.conversationId : "";
+    if (!externalId) return;
+    if (msg.type === "message.created") {
+      const raw = msg.message && typeof msg.message === "object" ? msg.message : null;
+      const cached = raw ? asCachedMessage(raw) : null;
+      if (cached) {
+        upsertMessage(externalId, cached);
+        return;
+      }
+      void refreshConversation(externalId).catch(() => void 0);
+      return;
+    }
+    if (msg.type === "message.updated") {
+      const raw = msg.message && typeof msg.message === "object" ? msg.message : null;
+      const cached = raw ? asCachedMessage(raw) : null;
+      if (cached) {
+        upsertMessage(externalId, cached);
+        return;
+      }
+      void refreshConversation(externalId).catch(() => void 0);
+      return;
+    }
+    if (msg.type === "message.deleted") {
+      const ids = Array.isArray(msg.ids) ? msg.ids.filter((id) => typeof id === "string") : [];
+      deleteMessages(externalId, ids);
+    }
+  };
+  const stopSocket = () => {
+    if (pingTimer) {
+      clearInterval(pingTimer);
+      pingTimer = null;
+    }
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    try {
+      socket?.close();
+    } catch {
+    }
+    socket = null;
+  };
+  const connectRealtime = () => {
+    if (stopped) return;
+    const WebSocketCtor = globalThis.WebSocket;
+    if (!WebSocketCtor) {
+      info("WebSocket unavailable; cache will refresh after local writes only");
+      return;
+    }
+    const ws = new WebSocketCtor(toWsUrl(maintainerProUrl, apiKey));
+    socket = ws;
+    ws.addEventListener("open", () => {
+      reconnectAttempt = 0;
+      logger.debug("store websocket open");
+      if (pingTimer) clearInterval(pingTimer);
+      pingTimer = setInterval(() => {
+        try {
+          if (ws.readyState === 1) ws.send(JSON.stringify({ type: "ping" }));
+        } catch {
+        }
+      }, 2e4);
+    });
+    ws.addEventListener("message", (event) => {
+      let payload;
+      try {
+        payload = JSON.parse(String(event.data));
+      } catch {
+        return;
+      }
+      if (payload.type === "hello") {
+        const meta = payload.meta && typeof payload.meta === "object" ? payload.meta : null;
+        const sandboxId = typeof meta?.sandboxId === "string" ? meta.sandboxId : "";
+        if (sandboxId && ws.readyState === 1) {
+          ws.send(
+            JSON.stringify({ type: "subscribe", channels: [`sandbox:${sandboxId}`] })
+          );
+        }
+        logger.debug({ sandboxId }, "store websocket hello");
+        return;
+      }
+      if (payload.type === "message.created" || payload.type === "message.updated" || payload.type === "message.deleted") {
+        logger.debug({ type: payload.type }, "store websocket event");
+        applyEvent(payload);
+      }
+    });
+    ws.addEventListener("close", () => {
+      if (socket === ws) socket = null;
+      if (pingTimer) {
+        clearInterval(pingTimer);
+        pingTimer = null;
+      }
+      if (stopped) return;
+      const delay = Math.min(3e4, 1e3 * 2 ** Math.min(reconnectAttempt, 5));
+      reconnectAttempt += 1;
+      logger.debug({ delay, reconnectAttempt }, "store websocket reconnect");
+      reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
+        void hydrate().catch((err) => {
+          logger.warn(
+            `cache rehydrate failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }).finally(() => {
+          connectRealtime();
+        });
+      }, delay);
+    });
+  };
+  const ready = hydrate().catch((err) => {
+    logger.warn(
+      `cache hydrate failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return stats();
+  });
+  void ready.then(() => {
+    if (!stopped) connectRealtime();
+  });
+  const store = {
+    ready,
+    stop: () => {
+      stopped = true;
+      stopSocket();
+    },
+    async ensureConversation(id) {
+      await remote.ensureConversation(id);
+      if (!conversations.has(id)) {
+        putConversation(id, []);
+      }
+    },
+    async saveMessage(input) {
+      const saved = await remote.saveMessage(input);
+      await refreshConversation(input.conversationId).catch(() => void 0);
+      return saved;
+    },
+    async listMessages(conversationId) {
+      await ready.catch(() => void 0);
+      const hit = conversations.get(conversationId);
+      if (hit) return cloneMessages(hit.messages);
+      return refreshConversation(conversationId);
+    },
+    async clearWorkingMessages(conversationId) {
+      await remote.clearWorkingMessages?.(conversationId);
+      await refreshConversation(conversationId).catch(() => void 0);
+    },
+    async releaseWorkingTurn(conversationId, parentMessageId) {
+      const result = await remote.releaseWorkingTurn?.(
+        conversationId,
+        parentMessageId
+      );
+      await refreshConversation(conversationId).catch(() => void 0);
+      return result ?? { nextQueued: null };
+    },
+    async recoverQueue(conversationId) {
+      const result = await remote.recoverQueue?.(conversationId);
+      await refreshConversation(conversationId).catch(() => void 0);
+      const conv = conversations.get(conversationId);
+      if (conv) {
+        const working = conv.messages.find(
+          (row) => row.role === "user" && row.queueStatus === "working" && row.senderType !== "developer"
+        );
+        if (working && !userHasAiReply2(conv.messages, working.id)) {
+          logger.info(
+            { conversationId, messageId: working.id, action: result?.action },
+            "recoverQueue \u2192 resume working turn"
+          );
+          onWorkingTurn?.({ conversationId, message: working });
+        }
+      }
+      return result ?? {
+        action: "noop",
+        workingId: null,
+        promotedId: null,
+        nextQueued: null
+      };
+    },
+    async listConversations() {
+      await ready.catch(() => void 0);
+      return [...conversations.values()].map((conv) => ({
+        id: conv.id,
+        updatedAt: conv.updatedAt,
+        messages: cloneMessages(conv.messages)
+      })).sort(
+        (a, b) => (Date.parse(b.updatedAt) || 0) - (Date.parse(a.updatedAt) || 0)
+      );
+    },
+    async saveToolEvents(conversationId, events) {
+      await remote.saveToolEvents?.(conversationId, events);
+    },
+    async uploadAttachments(conversationId, attachments) {
+      if (!remote.uploadAttachments) {
+        return { refs: [], localPaths: [] };
+      }
+      return remote.uploadAttachments(conversationId, attachments);
+    },
+    async materializeMessageAttachments(conversationId, messageId, workspaceDir) {
+      if (!remote.materializeMessageAttachments) return [];
+      return remote.materializeMessageAttachments(
+        conversationId,
+        messageId,
+        workspaceDir
+      );
+    }
+  };
+  return store;
+}
+
+// src/http/maintainer-pro-store.ts
+async function mpFetch(baseUrl, apiKey, pathName, init, fetchImpl) {
+  const url = `${baseUrl.replace(/\/$/, "")}${pathName}`;
+  const res = await fetchImpl(url, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+      ...init?.headers ?? {}
+    }
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(
+      `Maintainer Pro ${pathName} failed (${res.status}): ${text || res.statusText}`
+    );
+  }
+  const contentType = res.headers.get("content-type") ?? "";
   if (contentType.includes("application/json")) {
     return res.json();
   }
@@ -965,7 +2201,8 @@ function createMaintainerProStore(options) {
   const baseUrl = options.baseUrl;
   const apiKey = options.apiKey;
   const fetchImpl = options.fetchImpl ?? fetch;
-  const tempDir = options.tempDir ?? path4.join(os.tmpdir(), "maintainer-pro-store");
+  const logger = options.logger;
+  const tempDir = options.tempDir ?? projectUploadsDir({ workspaceDir: process.cwd() });
   const store = {
     async ensureConversation(id) {
       await mpFetch(
@@ -988,17 +2225,54 @@ function createMaintainerProStore(options) {
         {
           method: "POST",
           body: JSON.stringify({
+            id: input.id,
             role: input.role,
             content: input.content,
             provider: input.provider,
             senderType: input.senderType,
             senderName: input.senderName,
-            attachmentIds
+            parentMessageId: input.parentMessageId ?? void 0,
+            attachmentIds,
+            intent: input.intent,
+            queueStatus: input.queueStatus ?? void 0
           })
         },
         fetchImpl
       );
-      return data.message;
+      return {
+        ...data.message,
+        nextQueued: data.nextQueued ?? null
+      };
+    },
+    async releaseWorkingTurn(conversationId, parentMessageId) {
+      const data = await mpFetch(
+        baseUrl,
+        apiKey,
+        `/api/v1/store/conversations/${encodeURIComponent(conversationId)}/complete-turn`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            parentMessageId: parentMessageId ?? void 0
+          })
+        },
+        fetchImpl
+      );
+      return { nextQueued: data.nextQueued ?? null };
+    },
+    async recoverQueue(conversationId) {
+      const data = await mpFetch(
+        baseUrl,
+        apiKey,
+        `/api/v1/store/conversations/${encodeURIComponent(conversationId)}/recover-queue`,
+        { method: "POST", body: "{}" },
+        fetchImpl
+      );
+      return {
+        action: data.action ?? "noop",
+        workingId: data.workingId ?? null,
+        promotedId: data.promotedId ?? null,
+        nextQueued: data.nextQueued ?? null
+      };
     },
     async clearWorkingMessages(conversationId) {
       await mpFetch(
@@ -1029,6 +2303,16 @@ function createMaintainerProStore(options) {
       );
       return data.conversations ?? [];
     },
+    async listSnapshot() {
+      const data = await mpFetch(
+        baseUrl,
+        apiKey,
+        `/api/v1/store/snapshot`,
+        { method: "GET" },
+        fetchImpl
+      );
+      return data.conversations ?? [];
+    },
     async saveToolEvents(conversationId, events) {
       if (!events.length) return;
       await mpFetch(
@@ -1046,7 +2330,7 @@ function createMaintainerProStore(options) {
       if (!attachments?.length) {
         return { refs: [], localPaths: [], attachmentIds: [] };
       }
-      await fs4.mkdir(tempDir, { recursive: true });
+      await fs5.mkdir(tempDir, { recursive: true });
       const refs = [];
       const localPaths = [];
       const attachmentIds = [];
@@ -1069,28 +2353,131 @@ function createMaintainerProStore(options) {
         const id = data.attachment.id;
         attachmentIds.push(id);
         refs.push(data.attachment.ref || `maintainer-pro://${id}`);
-        const ext = item.mimeType.includes("jpeg") || item.mimeType.includes("jpg") ? ".jpg" : item.mimeType.includes("webp") ? ".webp" : item.mimeType.includes("gif") ? ".gif" : ".png";
-        const localPath = path4.join(
+        const localPath = path6.join(
           tempDir,
-          `${conversationId}-${id}${ext}`
+          `${conversationId}-${id}${extForMime(item.mimeType)}`
         );
-        await fs4.writeFile(localPath, Buffer.from(item.data, "base64"));
+        await fs5.mkdir(path6.dirname(localPath), { recursive: true });
+        await fs5.writeFile(localPath, Buffer.from(item.data, "base64"));
         localPaths.push(localPath);
       }
       return { refs, localPaths, attachmentIds };
+    },
+    async materializeMessageAttachments(conversationId, messageId, workspaceDir) {
+      if (!conversationId || !workspaceDir) return [];
+      const data = await mpFetch(
+        baseUrl,
+        apiKey,
+        `/api/v1/store/conversations/${encodeURIComponent(conversationId)}/messages`,
+        { method: "GET" },
+        fetchImpl
+      );
+      const messages = data.messages ?? [];
+      const byId = new Map(messages.map((row) => [row.id, row]));
+      const refs = [];
+      const fromMessageIds = [];
+      const seenMsg = /* @__PURE__ */ new Set();
+      const pushRow = (row) => {
+        if (!row || seenMsg.has(row.id)) return;
+        seenMsg.add(row.id);
+        const before = refs.length;
+        refs.push(...row.attachmentPaths ?? []);
+        refs.push(
+          ...(row.attachmentIds ?? []).map((id) => `maintainer-pro://${id}`)
+        );
+        if (refs.length > before) fromMessageIds.push(row.id);
+      };
+      let current = messageId ? byId.get(messageId) : void 0;
+      while (current && !seenMsg.has(current.id)) {
+        pushRow(current);
+        const parentId = current.parentMessageId?.trim();
+        current = parentId ? byId.get(parentId) : void 0;
+      }
+      for (const row of messages) {
+        if (row.role && row.role !== "user") continue;
+        pushRow(row);
+      }
+      const seen = /* @__PURE__ */ new Set();
+      const ids = [];
+      for (const ref of refs) {
+        const id = attachmentIdFromRef(ref);
+        if (!id || seen.has(id)) continue;
+        seen.add(id);
+        ids.push(id);
+      }
+      const localPaths = [];
+      for (const id of ids.slice(0, 5)) {
+        const url = `${baseUrl.replace(/\/$/, "")}/api/v1/store/attachments/${encodeURIComponent(id)}`;
+        const res = await fetchImpl(url, {
+          headers: { Authorization: `Bearer ${apiKey}` }
+        });
+        if (!res.ok) {
+          continue;
+        }
+        const mime = res.headers.get("content-type") || "image/png";
+        const buffer = Buffer.from(await res.arrayBuffer());
+        if (!buffer.byteLength) continue;
+        const localPath = path6.join(
+          tempDir,
+          `${id}${extForMime(mime)}`
+        );
+        await fs5.mkdir(tempDir, { recursive: true });
+        await fs5.writeFile(localPath, buffer);
+        localPaths.push(localPath);
+      }
+      logger?.debug(
+        {
+          conversationId,
+          messageId,
+          fromMessageIds,
+          stored: ids.length,
+          written: localPaths.length
+        },
+        "materialize attachments"
+      );
+      return localPaths;
     }
   };
-  return store;
+  if (options.sync === false) {
+    return Object.assign(store, {
+      ready: Promise.resolve({ conversations: 0, messages: 0 }),
+      stop() {
+      }
+    });
+  }
+  return createSyncedChatStore({
+    remote: store,
+    maintainerProUrl: baseUrl,
+    apiKey,
+    logger: options.logger,
+    log: options.log,
+    onWorkingTurn: options.onWorkingTurn
+  });
 }
-function createMaintainerProStoreFromEnv() {
+function createMaintainerProStoreFromEnv(options) {
   const baseUrl = process.env.MAINTAINER_PRO_URL?.trim();
   const apiKey = process.env.MAINTAINER_PRO_API_KEY?.trim();
   if (!baseUrl || !apiKey) return null;
-  return createMaintainerProStore({ baseUrl, apiKey });
+  return createMaintainerProStore({
+    baseUrl,
+    apiKey,
+    tempDir: projectUploadsDir({
+      workspaceDir: process.env.AI_CLI_WORKSPACE || process.cwd(),
+      sandboxId: process.env.MAINTAINER_PRO_SANDBOX_ID,
+      dataDir: process.env.MAINTAINER_PRO_DATA_DIR
+    }),
+    logger: options?.logger,
+    log: options?.log,
+    sync: options?.sync,
+    onWorkingTurn: options?.onWorkingTurn
+  });
 }
 
 // src/workspace-inspect.ts
+import fs6 from "fs";
+import path7 from "path";
 import { z } from "zod";
+var CONFIG_INSPECT_TIMEOUT_MS = 18e3;
 var inspectJsonSchema = z.object({
   kind: z.enum(["next", "vite", "html", "empty", "other"]).optional(),
   name: z.string().max(200).optional(),
@@ -1160,6 +2547,154 @@ ${input.extraContext ? `${input.extraContext.trim()}
 
 ` : ""}Inspect this project, fix any setup gaps you can, and return the JSON report.`;
 }
+function readSnippet(file, max = 4e3) {
+  try {
+    const text = fs6.readFileSync(file, "utf8");
+    return text.length > max ? `${text.slice(0, max)}
+\u2026` : text;
+  } catch {
+    return null;
+  }
+}
+function envKeysOnly(file) {
+  try {
+    const keys = fs6.readFileSync(file, "utf8").split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("#") && line.includes("=")).map((line) => line.slice(0, line.indexOf("=")).trim()).filter(Boolean);
+    return keys.length ? keys.join("\n") : null;
+  } catch {
+    return null;
+  }
+}
+function gatherConfigSnippets(workspaceDir) {
+  const folder = path7.resolve(workspaceDir);
+  const parts = [];
+  const pkg = readSnippet(path7.join(folder, "package.json"));
+  if (pkg) parts.push(`### package.json
+\`\`\`json
+${pkg}
+\`\`\``);
+  for (const lock of [
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb"
+  ]) {
+    if (fs6.existsSync(path7.join(folder, lock))) {
+      parts.push(`### lockfile
+${lock}`);
+      break;
+    }
+  }
+  for (const rel of [
+    "vite.config.ts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "next.config.js",
+    "next.config.mjs",
+    "next.config.ts"
+  ]) {
+    const body = readSnippet(path7.join(folder, rel), 2500);
+    if (body) parts.push(`### ${rel}
+\`\`\`
+${body}
+\`\`\``);
+  }
+  for (const rel of [".env.example", ".env", ".env.local", ".env.development"]) {
+    const keys = envKeysOnly(path7.join(folder, rel));
+    if (keys) parts.push(`### ${rel} keys (values omitted)
+\`\`\`
+${keys}
+\`\`\``);
+  }
+  return parts.join("\n\n") || "(no config files found)";
+}
+function configOnlySystemPrompt(input) {
+  return `You are Maintainer Pro's read-only setup advisor.
+
+Workspace: ${input.workspaceDir}
+App name: ${input.appName || "the app"}
+
+You are given configuration file excerpts only.
+DO NOT edit, create, or delete any files.
+DO NOT run shell commands, install packages, or start servers.
+Only infer how this project runs locally from the excerpts.
+
+Script names you report MUST appear in package.json scripts. Omit chat/ai-server scripts.
+
+Reply with a short human summary AND one \`\`\`json fence with:
+
+{
+  "kind": "next" | "vite" | "html" | "empty" | "other",
+  "name": "package or folder name",
+  "summary": "one sentence about this project",
+  "scripts": { "ui": "dev:client", "backend": "dev:server" },
+  "ports": { "ui": 5173, "backend": 4100 },
+  "issues": ["uncertainties"],
+  "fixes": [],
+  "ready": true
+}`;
+}
+function configOnlyUserMessage(input, snippets) {
+  return `${input.extraContext ? `${input.extraContext.trim()}
+
+` : ""}Analyze these config excerpts and suggest local apps/ports/scripts. Do not change anything on disk.
+
+${snippets}`;
+}
+function toInspectResult(input, text, providerId) {
+  const parsed = extractInspectJson(text);
+  return {
+    kind: parsed?.kind ?? "other",
+    name: parsed?.name?.trim() || input.appName || "",
+    summary: parsed?.summary?.trim() || text.replace(/```json[\s\S]*```/i, "").trim().slice(0, 400),
+    scripts: parsed?.scripts ?? {},
+    ports: parsed?.ports ?? {},
+    issues: parsed?.issues ?? [],
+    fixes: parsed?.fixes ?? [],
+    ready: parsed?.ready ?? parsed?.issues?.length === 0,
+    provider: providerId,
+    rawText: text
+  };
+}
+async function inspectConfigOnly(input, opts = {}) {
+  const workspaceDir = path7.resolve(input.workspaceDir);
+  const timeoutMs = opts.timeoutMs ?? CONFIG_INSPECT_TIMEOUT_MS;
+  const provider = await resolveProvider({ preference: "auto" });
+  const snippets = gatherConfigSnippets(workspaceDir);
+  const call = callAi(
+    [{ role: "user", content: configOnlyUserMessage(input, snippets) }],
+    {
+      route: "/local-setup-propose",
+      pageTitle: input.appName || "Setup suggestions",
+      relevantFiles: ["package.json", ".env.example"],
+      data: {
+        workspaceDir,
+        readOnly: true
+      }
+    },
+    {
+      systemPrompt: configOnlySystemPrompt(input),
+      workspaceDir,
+      technical: true
+    }
+  );
+  const timed = await Promise.race([
+    call.then((response) => ({ ok: true, response })),
+    new Promise(
+      (resolve) => setTimeout(
+        () => resolve({ ok: false, error: `Config inspect timed out after ${timeoutMs}ms` }),
+        timeoutMs
+      )
+    )
+  ]);
+  if (!timed.ok) {
+    throw new Error(timed.error);
+  }
+  return toInspectResult(
+    input,
+    timed.response.text,
+    timed.response.provider || provider.id
+  );
+}
 async function inspectAndRepairWorkspace(input) {
   const workspaceDir = input.workspaceDir;
   const provider = await resolveProvider({ preference: "auto" });
@@ -1180,27 +2715,678 @@ async function inspectAndRepairWorkspace(input) {
       technical: true
     }
   );
-  const parsed = extractInspectJson(response.text);
+  return toInspectResult(
+    input,
+    response.text,
+    response.provider || provider.id
+  );
+}
+
+// src/host-apps.ts
+import fs7 from "fs";
+import path8 from "path";
+import { createHash as createHash2 } from "crypto";
+var COLLABORATER_DIR = ".collaborater";
+var AI_SERVER_APP_ID = "ai-server";
+var AI_SERVER_DEFAULT_PORT = 3100;
+var ENV_FILES = [".env", ".env.local", ".env.development", ".env.example"];
+function isPort(value) {
+  return Number.isInteger(value) && Number(value) >= 1024 && Number(value) <= 65535;
+}
+function parsePort(value, fallback = 0) {
+  if (typeof value === "number" && isPort(value)) return value;
+  const text = String(value ?? "").trim();
+  if (!text) return fallback;
+  if (/^\d{2,5}$/.test(text)) {
+    const n = Number(text);
+    return isPort(n) ? n : fallback;
+  }
+  try {
+    const port = Number(new URL(text).port);
+    return isPort(port) ? port : fallback;
+  } catch {
+    const match = text.match(/--port(?:\s+|=)(\d{2,5})/i) || text.match(/\bPORT[=:]\s*(\d{2,5})/i) || text.match(/:(\d{2,5})\b/);
+    const n = match ? Number(match[1]) : 0;
+    return isPort(n) ? n : fallback;
+  }
+}
+function dataInput(folder, extra) {
   return {
-    kind: parsed?.kind ?? "other",
-    name: parsed?.name?.trim() || input.appName || "",
-    summary: parsed?.summary?.trim() || response.text.replace(/```json[\s\S]*```/i, "").trim().slice(0, 400),
-    scripts: parsed?.scripts ?? {},
-    ports: parsed?.ports ?? {},
-    issues: parsed?.issues ?? [],
-    fixes: parsed?.fixes ?? [],
-    ready: parsed?.ready ?? parsed?.issues?.length === 0,
-    provider: response.provider || provider.id,
-    rawText: response.text
+    workspaceDir: folder,
+    sandboxId: extra?.sandboxId,
+    dataDir: extra?.dataDir
+  };
+}
+function hostAppsCachePath2(folder, extra) {
+  return hostAppsCachePath(dataInput(folder, extra));
+}
+function defaultAiServerApp(port = AI_SERVER_DEFAULT_PORT) {
+  return {
+    id: AI_SERVER_APP_ID,
+    name: "AI server",
+    role: "ai-server",
+    port: parsePort(port, AI_SERVER_DEFAULT_PORT),
+    startCommand: null,
+    source: "default",
+    locked: true
+  };
+}
+function normalizeHostApp(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const row = raw;
+  const port = parsePort(row.port);
+  if (!port) return null;
+  const role = String(row.role || "custom");
+  const allowed = ["ai-server", "ui", "backend", "app", "custom"];
+  const id = String(row.id || "").trim() || (role === "ai-server" ? AI_SERVER_APP_ID : "");
+  if (!id) return null;
+  return {
+    id: id.slice(0, 64),
+    name: String(row.name || id).trim().slice(0, 80) || id,
+    role: allowed.includes(role) ? role : "custom",
+    port,
+    startCommand: typeof row.startCommand === "string" && row.startCommand.trim() ? row.startCommand.trim().slice(0, 200) : null,
+    source: ["default", "env", "package", "ai", "manual"].includes(
+      row.source
+    ) ? row.source : "manual",
+    locked: row.locked === true || id === AI_SERVER_APP_ID || role === "ai-server",
+    host: role !== "ai-server" && id !== AI_SERVER_APP_ID && row.host === true,
+    envMaps: normalizeEnvMaps(row.envMaps)
+  };
+}
+function normalizeEnvMaps(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const row = item;
+    const key = String(row.key || "").trim();
+    const sourceAppId = String(row.sourceAppId || "").trim().slice(0, 64);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || key.length > 80) continue;
+    if (!sourceAppId || seen.has(key)) continue;
+    seen.add(key);
+    out.push({ key, sourceAppId });
+  }
+  return out.slice(0, 30);
+}
+function ensureSingleHost(apps) {
+  const next = apps.map((app) => ({
+    ...app,
+    host: app.role !== "ai-server" && app.id !== AI_SERVER_APP_ID && app.host === true
+  }));
+  const marked = next.filter((app) => app.host);
+  if (marked.length === 1) return next;
+  if (marked.length > 1) {
+    let kept = false;
+    return next.map((app) => {
+      if (!app.host) return app;
+      if (kept) return { ...app, host: false };
+      kept = true;
+      return app;
+    });
+  }
+  const fallback = next.find((app) => app.role === "ui" || app.role === "app") || next.find((app) => app.role !== "ai-server");
+  return next.map(
+    (app) => fallback && app.id === fallback.id ? { ...app, host: true } : app
+  );
+}
+function normalizeHostApps(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const apps = [];
+  for (const item of raw) {
+    const app = normalizeHostApp(item);
+    if (!app || seen.has(app.id)) continue;
+    seen.add(app.id);
+    apps.push(app);
+  }
+  return apps;
+}
+function ensureAiServerApp(apps, preferredPort = AI_SERVER_DEFAULT_PORT) {
+  const next = normalizeHostApps(apps);
+  const existing = next.find((app) => app.id === AI_SERVER_APP_ID || app.role === "ai-server");
+  if (existing) {
+    existing.id = AI_SERVER_APP_ID;
+    existing.role = "ai-server";
+    existing.locked = true;
+    existing.host = false;
+    existing.name = existing.name || "AI server";
+    return ensureSingleHost([existing, ...next.filter((app) => app !== existing)]);
+  }
+  return ensureSingleHost([defaultAiServerApp(preferredPort), ...next]);
+}
+function readText(file) {
+  try {
+    return fs7.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+function readEnvFileMap(file) {
+  const text = readText(file);
+  if (!text) return {};
+  const map = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    if (key) map[key] = value;
+  }
+  return map;
+}
+function readProjectEnvLayers(folder) {
+  const resolved = path8.resolve(folder);
+  const layers = [];
+  const merged = {};
+  for (const name of ENV_FILES) {
+    const file = path8.join(resolved, name);
+    const values = readEnvFileMap(file);
+    if (!Object.keys(values).length) continue;
+    layers.push({ file: name, values });
+    if (name === ".env.example") continue;
+    Object.assign(merged, values);
+  }
+  return { merged, layers };
+}
+function readPackageJson(folder) {
+  try {
+    return JSON.parse(fs7.readFileSync(path8.join(folder, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isChatScript(name, command) {
+  return /\b(ai-server|ai-cli|dev:chat|start:chat)\b/i.test(`${name} ${command}`);
+}
+function isUiCommand(command) {
+  return /\b(vite|next|nuxt|astro|remix|react-scripts|webpack-dev-server|parcel)\b/i.test(
+    command
+  );
+}
+function configPort(folder, files) {
+  for (const rel of files) {
+    const text = readText(path8.join(folder, rel));
+    if (!text) continue;
+    const match = text.match(/\bport\s*[:=]\s*(\d{2,5})/i) || text.match(/--port(?:\s+|=)(\d{2,5})/i);
+    const port = parsePort(match?.[1]);
+    if (port) return port;
+  }
+  return 0;
+}
+function hostAppsFingerprint(folder) {
+  const resolved = path8.resolve(folder);
+  const parts = [];
+  for (const rel of [
+    "package.json",
+    ...ENV_FILES,
+    "vite.config.ts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "next.config.js",
+    "next.config.mjs",
+    "next.config.ts"
+  ]) {
+    const file = path8.join(resolved, rel);
+    if (!fs7.existsSync(file)) continue;
+    try {
+      const st = fs7.statSync(file);
+      parts.push(`${rel}:${st.size}:${Math.floor(st.mtimeMs)}`);
+    } catch {
+    }
+  }
+  return createHash2("sha256").update(parts.join("|") || resolved).digest("hex").slice(0, 32);
+}
+function pickScript(scripts, names) {
+  return names.find((name) => scripts[name] && !isChatScript(name, scripts[name])) || null;
+}
+function detectHostAppsFromFiles(folder, opts = {}) {
+  const resolved = path8.resolve(folder);
+  const reasons = [];
+  const { merged, layers } = readProjectEnvLayers(resolved);
+  const pkg = readPackageJson(resolved);
+  const scripts = pkg?.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+  const apps = [];
+  const envAi = parsePort(merged.AI_SERVER_PORT) || parsePort(merged.AI_SERVER_URL);
+  const aiPort = envAi || parsePort(opts.preferredAiPort, AI_SERVER_DEFAULT_PORT);
+  apps.push({
+    ...defaultAiServerApp(aiPort),
+    source: envAi ? "env" : "default"
+  });
+  const envPorts = {
+    PORT: layers.filter((layer) => layer.file !== ".env.example").map((layer) => ({ file: layer.file, port: parsePort(layer.values.PORT) })).filter((row) => row.port),
+    APP_URL: parsePort(merged.APP_URL || merged.NEXT_PUBLIC_APP_URL || merged.PUBLIC_URL),
+    API_PORT: parsePort(merged.API_PORT || merged.API_URL || merged.VITE_API_URL)
+  };
+  const portValues = [...new Set(envPorts.PORT.map((row) => row.port))];
+  if (portValues.length > 1) {
+    reasons.push(
+      `PORT differs across env files: ${envPorts.PORT.map((row) => `${row.file}=${row.port}`).join(", ")}`
+    );
+  }
+  if (envPorts.PORT[0] && envPorts.APP_URL && envPorts.PORT[0].port !== envPorts.APP_URL) {
+    reasons.push(
+      `PORT=${envPorts.PORT[0].port} does not match APP_URL port ${envPorts.APP_URL}`
+    );
+  }
+  const uiScript = pickScript(scripts, [
+    "dev:client",
+    "dev:ui",
+    "dev:web",
+    "dev:frontend",
+    "client",
+    "start:client"
+  ]) || (scripts.dev && !isChatScript("dev", scripts.dev) ? "dev" : null);
+  const apiScript = pickScript(scripts, [
+    "dev:server",
+    "dev:backend",
+    "dev:api",
+    "server",
+    "start:server"
+  ]);
+  const vitePort = configPort(resolved, ["vite.config.ts", "vite.config.js", "vite.config.mjs"]) || 5173;
+  const nextPort = configPort(resolved, ["next.config.js", "next.config.mjs", "next.config.ts"]) || 3e3;
+  const portFromEnv = parsePort(merged.PORT);
+  const hostFromEnv = parsePort(merged.HOST_PORT) || parsePort(merged.HOST_URL) || parsePort(merged.CORS_ORIGIN);
+  const uiFromEnv = hostFromEnv || envPorts.APP_URL || (portFromEnv && portFromEnv !== aiPort ? portFromEnv : 0);
+  if (uiScript) {
+    const command = scripts[uiScript] || "";
+    const scriptPort = parsePort(command);
+    const fallback = isUiCommand(command) && /vite/i.test(command) ? vitePort : nextPort;
+    const port = uiFromEnv || scriptPort || fallback;
+    apps.push({
+      id: "ui",
+      name: opts.appName || pkg?.name || "App",
+      role: isUiCommand(command) ? "ui" : "app",
+      port,
+      startCommand: `npm run ${uiScript}`,
+      source: uiFromEnv ? "env" : scriptPort ? "package" : "package",
+      host: true
+    });
+  } else if (uiFromEnv) {
+    apps.push({
+      id: "ui",
+      name: opts.appName || pkg?.name || "App",
+      role: "ui",
+      port: uiFromEnv,
+      startCommand: scripts.dev ? "npm run dev" : null,
+      source: "env",
+      host: true
+    });
+  }
+  if (apiScript && apiScript !== uiScript) {
+    const command = scripts[apiScript] || "";
+    const port = envPorts.API_PORT || parsePort(command) || configPort(resolved, []) || 4100;
+    apps.push({
+      id: "backend",
+      name: "Backend",
+      role: "backend",
+      port,
+      startCommand: `npm run ${apiScript}`,
+      source: envPorts.API_PORT ? "env" : "package"
+    });
+  }
+  const hostApps = apps.filter((app) => app.role !== "ai-server");
+  if (pkg && Object.keys(scripts).length && hostApps.length === 0) {
+    reasons.push("Found package.json scripts but no host app port in env or config");
+  }
+  return {
+    apps: ensureAiServerApp(apps, aiPort),
+    reasons,
+    confused: reasons.length > 0
+  };
+}
+function readHostAppsCache(folder, extra) {
+  try {
+    const raw = JSON.parse(
+      fs7.readFileSync(hostAppsCachePath2(folder, extra), "utf8")
+    );
+    const apps = ensureAiServerApp(normalizeHostApps(raw.apps));
+    if (!apps.length) return null;
+    return {
+      apps,
+      fingerprint: typeof raw.fingerprint === "string" ? raw.fingerprint : void 0,
+      updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : void 0
+    };
+  } catch {
+    return null;
+  }
+}
+var readCollaboraterApps = readHostAppsCache;
+function writeHostAppsCache(folder, apps, extra = {}, loc) {
+  const resolved = path8.resolve(folder);
+  ensureProjectDataDir(dataInput(resolved, loc));
+  const payload = {
+    version: 1,
+    fingerprint: hostAppsFingerprint(resolved),
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    apps: ensureAiServerApp(apps),
+    ...extra
+  };
+  fs7.writeFileSync(
+    hostAppsCachePath2(resolved, loc),
+    `${JSON.stringify(payload, null, 2)}
+`,
+    "utf8"
+  );
+}
+var writeCollaboraterApps = writeHostAppsCache;
+function mergeDesiredHostApps(desired, detected) {
+  const byId = new Map(detected.map((app) => [app.id, app]));
+  const byRole = new Map(detected.map((app) => [app.role, app]));
+  const merged = desired.map((app) => {
+    const local = byId.get(app.id) || (app.role !== "custom" ? byRole.get(app.role) : void 0);
+    return {
+      ...local,
+      ...app,
+      startCommand: app.startCommand || local?.startCommand || null,
+      locked: app.locked || app.id === AI_SERVER_APP_ID || app.role === "ai-server",
+      host: app.role === "ai-server" || app.id === AI_SERVER_APP_ID ? false : app.host === true || app.host !== false && local?.host === true,
+      envMaps: app.envMaps && app.envMaps.length ? app.envMaps : local?.envMaps || []
+    };
+  });
+  return ensureAiServerApp(merged);
+}
+function appsFromInspectPorts(ports, scripts, name) {
+  const apps = [];
+  if (ports.ui || scripts.ui) {
+    apps.push({
+      id: "ui",
+      name,
+      role: "ui",
+      port: parsePort(ports.ui, 5173),
+      startCommand: scripts.ui ? `npm run ${scripts.ui}` : null,
+      source: "ai"
+    });
+  }
+  if (ports.backend || scripts.backend) {
+    apps.push({
+      id: "backend",
+      name: "Backend",
+      role: "backend",
+      port: parsePort(ports.backend, 4100),
+      startCommand: scripts.backend ? `npm run ${scripts.backend}` : null,
+      source: "ai"
+    });
+  }
+  if (!apps.length && (ports.app || scripts.app)) {
+    apps.push({
+      id: "app",
+      name,
+      role: "app",
+      port: parsePort(ports.app, 3e3),
+      startCommand: scripts.app ? `npm run ${scripts.app}` : null,
+      source: "ai"
+    });
+  }
+  return apps;
+}
+function collectScriptAlternatives(folder, primary, opts = {}) {
+  const pkg = readPackageJson(folder);
+  const scripts = pkg?.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+  const usedCommands = new Set(
+    primary.map((app) => app.startCommand?.trim()).filter((cmd) => Boolean(cmd))
+  );
+  const alternatives = [];
+  const hostApp = primary.find((app) => app.role === "ui" || app.role === "app") || primary.find((app) => app.role !== "ai-server");
+  const backendApp = primary.find((app) => app.role === "backend");
+  for (const [name, command] of Object.entries(scripts)) {
+    if (isChatScript(name, command)) continue;
+    if (!/^(dev|start|serve)/i.test(name) && !isUiCommand(command)) continue;
+    const startCommand = `npm run ${name}`;
+    if (usedCommands.has(startCommand)) continue;
+    const scriptPort = parsePort(command);
+    const looksBackend = /\b(server|api|backend)\b/i.test(`${name} ${command}`) && !isUiCommand(command);
+    const target = looksBackend ? backendApp || hostApp : hostApp;
+    if (!target) continue;
+    const fallbackPort = scriptPort || (looksBackend ? 4100 : isUiCommand(command) && /vite/i.test(command) ? 5173 : 3e3);
+    alternatives.push({
+      appId: target.id,
+      port: fallbackPort,
+      startCommand,
+      label: `${name} \u2192 ${fallbackPort}`,
+      source: "package"
+    });
+    if (alternatives.length >= 8) break;
+  }
+  const { layers } = readProjectEnvLayers(folder);
+  if (hostApp) {
+    for (const layer of layers) {
+      if (layer.file === ".env.example") continue;
+      const port = parsePort(layer.values.PORT);
+      if (!port || port === hostApp.port) continue;
+      if (alternatives.some(
+        (alt) => alt.appId === hostApp.id && alt.port === port && !alt.startCommand
+      )) {
+        continue;
+      }
+      alternatives.push({
+        appId: hostApp.id,
+        port,
+        startCommand: hostApp.startCommand || null,
+        label: `${layer.file} PORT=${port}`,
+        source: "env"
+      });
+    }
+  }
+  void opts;
+  return alternatives;
+}
+function proposalConfidence(apps, reasons, usedAi) {
+  const hostApps = apps.filter((app) => app.role !== "ai-server");
+  if (!hostApps.length) return "low";
+  if (reasons.length === 0 && hostApps.every((app) => app.startCommand)) {
+    return usedAi ? "medium" : "high";
+  }
+  if (reasons.some((reason) => /differ|does not match|no host app/i.test(reason))) {
+    return "low";
+  }
+  return "medium";
+}
+function projectSummaryFromDetect(folder, apps, opts = {}) {
+  const pkg = readPackageJson(folder);
+  const name = opts.appName || pkg?.name || path8.basename(path8.resolve(folder));
+  const hostApps = apps.filter((app) => app.role !== "ai-server");
+  if (!hostApps.length) {
+    return `${name}: no UI/backend ports detected from config yet.`;
+  }
+  return `${name}: ${hostApps.map((app) => `${app.name} on ${app.port}${app.startCommand ? ` (${app.startCommand})` : ""}`).join(", ")}.`;
+}
+async function proposeHostAppsFromConfig(input) {
+  const folder = path8.resolve(input.workspaceDir);
+  const preferredAi = parsePort(input.preferredAiPort, AI_SERVER_DEFAULT_PORT);
+  const fingerprint = hostAppsFingerprint(folder);
+  const allowAi = input.allowAi !== false;
+  const detected = detectHostAppsFromFiles(folder, {
+    preferredAiPort: preferredAi,
+    appName: input.appName
+  });
+  let apps = ensureAiServerApp(detected.apps, preferredAi);
+  let reasons = [...detected.reasons];
+  let usedAi = false;
+  let projectSummary = projectSummaryFromDetect(folder, apps, {
+    appName: input.appName
+  });
+  const hostCount = apps.filter((app) => app.role !== "ai-server").length;
+  const needsAi = allowAi && (detected.confused || hostCount === 0 || reasons.some((reason) => /differ|does not match/i.test(reason)));
+  if (needsAi) {
+    try {
+      const inspected = await inspectConfigOnly({
+        workspaceDir: folder,
+        appName: input.appName,
+        extraContext: [
+          "File-based detection was uncertain or incomplete.",
+          ...reasons
+        ].join("\n")
+      });
+      usedAi = true;
+      const fromAi = appsFromInspectPorts(
+        inspected.ports,
+        inspected.scripts,
+        inspected.name || input.appName || "App"
+      );
+      if (fromAi.length) {
+        apps = ensureAiServerApp(
+          [defaultAiServerApp(preferredAi), ...fromAi],
+          preferredAi
+        );
+      }
+      if (inspected.summary) projectSummary = inspected.summary;
+      if (inspected.issues?.length) {
+        reasons = [...reasons, ...inspected.issues];
+      }
+    } catch (err) {
+      reasons.push(
+        `AI suggest skipped: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  const alternatives = collectScriptAlternatives(folder, apps, {
+    appName: input.appName
+  });
+  const confidence = proposalConfidence(apps, reasons, usedAi);
+  const needsReview = confidence !== "high" || detected.confused || apps.filter((app) => app.role !== "ai-server").length === 0;
+  return {
+    apps,
+    alternatives,
+    reasons,
+    confidence,
+    projectSummary,
+    usedAi,
+    needsReview,
+    fingerprint
+  };
+}
+async function resolveHostApps(input) {
+  const folder = path8.resolve(input.workspaceDir);
+  const loc = { sandboxId: input.sandboxId, dataDir: input.dataDir };
+  const fingerprint = hostAppsFingerprint(folder);
+  const preferredAi = parsePort(input.preferredAiPort, AI_SERVER_DEFAULT_PORT);
+  const detected = detectHostAppsFromFiles(folder, {
+    preferredAiPort: preferredAi,
+    appName: input.appName
+  });
+  const desired = normalizeHostApps(input.desired);
+  if (desired.length) {
+    const apps2 = mergeDesiredHostApps(desired, detected.apps);
+    try {
+      writeHostAppsCache(folder, apps2, { source: "desired" }, loc);
+    } catch {
+    }
+    return {
+      apps: apps2,
+      source: "desired",
+      cached: false,
+      usedAi: false,
+      confused: false,
+      reasons: [],
+      fingerprint
+    };
+  }
+  if (!input.force) {
+    const cached = readHostAppsCache(folder, loc);
+    if (cached && cached.fingerprint === fingerprint) {
+      return {
+        apps: ensureAiServerApp(cached.apps, preferredAi),
+        source: "cache",
+        cached: true,
+        usedAi: false,
+        confused: false,
+        reasons: [],
+        fingerprint
+      };
+    }
+  }
+  const needsAi = Boolean(input.allowAi) && (Boolean(input.force && detected.confused) || detected.confused && detected.apps.filter((app) => app.role !== "ai-server").length === 0 || detected.reasons.some((reason) => /differ|does not match/i.test(reason)));
+  if (needsAi) {
+    try {
+      const inspected = await inspectConfigOnly({
+        workspaceDir: folder,
+        appName: input.appName,
+        extraContext: `Port detection was uncertain:
+${detected.reasons.join("\n")}
+Return the real local ports and npm script names.`
+      });
+      const fromAi = appsFromInspectPorts(
+        inspected.ports,
+        inspected.scripts,
+        inspected.name || input.appName || "App"
+      );
+      const apps2 = ensureAiServerApp(
+        [defaultAiServerApp(preferredAi), ...fromAi],
+        preferredAi
+      );
+      writeHostAppsCache(
+        folder,
+        apps2,
+        {
+          source: "ai",
+          reasons: detected.reasons,
+          summary: inspected.summary
+        },
+        loc
+      );
+      return {
+        apps: apps2,
+        source: "ai",
+        cached: false,
+        usedAi: true,
+        confused: detected.confused,
+        reasons: detected.reasons,
+        fingerprint
+      };
+    } catch (err) {
+      detected.reasons.push(
+        `AI inspect skipped: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  const apps = ensureAiServerApp(detected.apps, preferredAi);
+  try {
+    writeHostAppsCache(
+      folder,
+      apps,
+      {
+        source: detected.confused ? "env" : "env",
+        reasons: detected.reasons
+      },
+      loc
+    );
+  } catch {
+  }
+  return {
+    apps,
+    source: apps.some((app) => app.source === "env") ? "env" : "default",
+    cached: false,
+    usedAi: false,
+    confused: detected.confused,
+    reasons: detected.reasons,
+    fingerprint
   };
 }
 export {
+  ACCESS_IGNORE_BEGIN,
+  ACCESS_IGNORE_END,
+  AI_SERVER_APP_ID,
+  AI_SERVER_DEFAULT_PORT,
+  COLLABORATER_DIR,
+  DEFAULT_AI_IGNORE_PATHS,
+  HOST_APPS_FILE,
+  MAINTAINER_PRO_HOME_DIR,
+  PROMPT_SECTION,
   WORKING_PROVIDER,
   buildClaudeUserPrompt,
   buildConversationPrompt,
   buildCursorPrompt,
   buildPriorConversationsContext,
   callAi,
+  collectParentChain,
   commandExists,
   createAntigravityProvider,
   createBuiltinProviders,
@@ -1208,17 +3394,60 @@ export {
   createClaudeProvider,
   createCursorProvider,
   createDefaultSystemPrompt,
+  createInfoLogger,
   createLocalDirectoryStore,
+  createLogger,
   createMaintainerProStore,
   createMaintainerProStoreFromEnv,
+  createSyncedChatStore,
   createToolValidator,
+  defaultAiServerApp,
+  detectHostAppsFromFiles,
+  ensureAiServerApp,
+  ensureProjectDataDir,
+  ensureSingleHost,
+  formatAccessPolicyPromptSection,
   formatClientContext,
+  formatParentChainContext,
   getProviderPreference,
+  hostAppsCachePath2 as hostAppsCachePath,
+  hostAppsFingerprint,
   inspectAndRepairWorkspace,
+  inspectConfigOnly,
+  isDevMode,
+  isIgnoredRelative,
+  isInsideWorkspace,
+  isPathAllowed,
+  maintainerProHome,
+  mergeDesiredHostApps,
+  normalizeEnvMaps,
+  normalizeHostApp,
+  normalizeHostApps,
+  normalizeIgnorePaths,
+  parentChainForTurn,
   parseAiResponse,
+  parseIgnorePathsEnv,
+  parsePort,
+  previewText,
+  hostAppsCachePath as projectHostAppsPath,
+  projectIdForFolder,
+  projectUploadsDir,
+  proposeHostAppsFromConfig,
   providerLabel,
+  readCollaboraterApps,
+  readHostAppsCache,
+  readProjectEnvLayers,
+  renderManagedIgnoreBlock,
   resolveCliBinary,
+  resolveHostApps,
+  resolveIgnorePaths,
+  resolveLogLevel,
+  resolveProjectDataDir,
   resolveProvider,
+  sanitizeProjectId,
   saveChatAttachments,
-  toNextRoute
+  toNextRoute,
+  upsertManagedIgnoreFile,
+  writeCollaboraterApps,
+  writeHostAppsCache
 };