@maintainer-pro/ai-cli 0.1.3 → 0.1.5

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,47 +80,67 @@ function splitMessages(messages) {
   const history = latestUserIndex > 0 ? messages.slice(0, latestUserIndex) : [];
   return { request, history };
 }
-function buildUserFacingPrompt(systemPrompt, messages, context, attachmentPaths, priorConversationsContext) {
+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")}
-
-` : "";
-  return `${systemSection}${contextSection}${priorSection}${historyBlock}${attachmentsSection}Current user request:
-${request || "(See the attached screenshot(s).)"}
-
-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.`;
+  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):
+${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}${parentSection}${historySection}${attachmentsSection}${currentSection}${closer}`;
 }
-function buildCursorPrompt(systemPrompt, messages, context, attachmentPaths, priorConversationsContext) {
+function buildCursorPrompt(systemPrompt, messages, context, attachmentPaths, priorConversationsContext, technical, parentChainContext) {
   return buildUserFacingPrompt(
     systemPrompt,
     messages,
     context,
     attachmentPaths,
-    priorConversationsContext
+    priorConversationsContext,
+    technical,
+    parentChainContext
   );
 }
-function buildClaudeUserPrompt(messages, context, attachmentPaths, priorConversationsContext) {
+function buildClaudeUserPrompt(messages, context, attachmentPaths, priorConversationsContext, technical, parentChainContext) {
   return buildUserFacingPrompt(
     null,
     messages,
     context,
     attachmentPaths,
-    priorConversationsContext
+    priorConversationsContext,
+    technical,
+    parentChainContext
   );
 }
 
@@ -196,7 +253,9 @@ async function callClaudeCli(command, messages, context, options) {
     messages,
     context,
     options.attachmentPaths,
-    options.priorConversationsContext
+    options.priorConversationsContext,
+    options.technical,
+    options.parentChainContext
   );
   const resolved = resolveCliCommand("claude", command);
   const workspace = options.workspaceDir ?? process.env.AI_CLI_WORKSPACE ?? process.cwd();
@@ -235,7 +294,9 @@ async function callCursorCli(command, messages, context, options) {
     messages,
     context,
     options.attachmentPaths,
-    options.priorConversationsContext
+    options.priorConversationsContext,
+    options.technical,
+    options.parentChainContext
   );
   const resolved = resolveCliCommand("cursor", command);
   const workspace = options.workspaceDir ?? process.env.AI_CLI_WORKSPACE ?? process.cwd();
@@ -276,7 +337,9 @@ async function callAntigravityCli(command, messages, context, options) {
     messages,
     context,
     options.attachmentPaths,
-    options.priorConversationsContext
+    options.priorConversationsContext,
+    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).
 
@@ -317,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 path6 = result.stdout.trim().split(/\r?\n/)[0]?.trim();
+    return path6 || null;
   } catch {
     return null;
   }
@@ -404,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):
@@ -414,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.length ? input.ignorePaths.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}
@@ -434,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}
 
@@ -441,9 +558,191 @@ 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/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.length ? input.ignorePaths.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 read, write, move, or delete files outside that workspace.
+- 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 fs2 from "fs/promises";
-import path2 from "path";
+import path3 from "path";
 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"]);
@@ -463,7 +762,7 @@ function extForMime(mime) {
 async function saveChatAttachments(attachments, workspaceDir) {
   if (!attachments?.length) return [];
   const selected = attachments.slice(0, MAX_ATTACHMENTS);
-  const dir = path2.join(workspaceDir, ".maintainer-pro", "uploads");
+  const dir = path3.join(workspaceDir, ".maintainer-pro", "uploads");
   await fs2.mkdir(dir, { recursive: true });
   const paths = [];
   const stamp = Date.now();
@@ -482,7 +781,10 @@ 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);
+    const filePath = path3.resolve(dir, fileName);
+    if (!isInsideWorkspace(workspaceDir, filePath)) {
+      throw new Error("Attachment path escaped the project workspace");
+    }
     await fs2.writeFile(filePath, buffer);
     paths.push(filePath);
   }
@@ -569,7 +871,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({
@@ -577,9 +879,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) {
@@ -614,6 +933,7 @@ 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 baseCallOptions = {
@@ -622,6 +942,7 @@ function createChatHandler(options) {
     providerPreference: options.providerPreference,
     providers: options.providers
   };
+  logger.debug({ workspaceDir }, "chat handler ready");
   return {
     async GET(request) {
       try {
@@ -637,6 +958,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),
@@ -644,6 +973,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 },
@@ -653,7 +983,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(
@@ -662,6 +994,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(
@@ -686,11 +1031,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 });
@@ -721,27 +1109,65 @@ function createChatHandler(options) {
         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
@@ -752,23 +1178,58 @@ 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,
+            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
@@ -776,38 +1237,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(
           {
@@ -828,8 +1359,13 @@ function toNextRoute(handlers) {
 
 // src/http/local-store.ts
 import fs3 from "fs/promises";
-import path3 from "path";
-import { randomUUID } from "crypto";
+import path4 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");
@@ -840,11 +1376,11 @@ async function readConversation(filePath) {
   }
 }
 async function writeConversation(filePath, data) {
-  await fs3.mkdir(path3.dirname(filePath), { recursive: true });
+  await fs3.mkdir(path4.dirname(filePath), { recursive: true });
   await fs3.writeFile(filePath, JSON.stringify(data, null, 2), "utf8");
 }
 function createLocalDirectoryStore(baseDir) {
-  const fileFor = (id) => path3.join(baseDir, `${id}.json`);
+  const fileFor = (id) => path4.join(baseDir, `${id}.json`);
   return {
     async ensureConversation(id) {
       const existing = await readConversation(fileFor(id));
@@ -862,21 +1398,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;
+      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 next ? { nextQueued: { id: next.id, content: next.content } } : { nextQueued: null };
     },
     async clearWorkingMessages(conversationId) {
       const filePath = fileFor(conversationId);
@@ -898,7 +1686,7 @@ function createLocalDirectoryStore(baseDir) {
       const conversations = [];
       for (const entry of entries) {
         if (!entry.endsWith(".json")) continue;
-        const filePath = path3.join(baseDir, entry);
+        const filePath = path4.join(baseDir, entry);
         const existing = await readConversation(filePath);
         if (!existing?.id) continue;
         conversations.push({
@@ -915,7 +1703,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 = path4.join(baseDir, `${conversationId}.tools.jsonl`);
       const lines = events.map(
         (e) => JSON.stringify({
           conversationId,
@@ -932,7 +1720,353 @@ function createLocalDirectoryStore(baseDir) {
 // src/http/maintainer-pro-store.ts
 import fs4 from "fs/promises";
 import os from "os";
-import path4 from "path";
+import path5 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") : 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);
+    }
+  };
+  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, {
@@ -959,7 +2093,7 @@ 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 tempDir = options.tempDir ?? path5.join(os.tmpdir(), "maintainer-pro-store");
   const store = {
     async ensureConversation(id) {
       await mpFetch(
@@ -982,17 +2116,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,
+        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 data.message;
+      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(
@@ -1023,6 +2194,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(
@@ -1064,7 +2245,7 @@ function createMaintainerProStore(options) {
         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 = path5.join(
           tempDir,
           `${conversationId}-${id}${ext}`
         );
@@ -1074,21 +2255,153 @@ function createMaintainerProStore(options) {
       return { refs, localPaths, attachmentIds };
     }
   };
-  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,
+    logger: options?.logger,
+    log: options?.log,
+    sync: options?.sync,
+    onWorkingTurn: options?.onWorkingTurn
+  });
+}
+
+// src/workspace-inspect.ts
+import { z } from "zod";
+var inspectJsonSchema = z.object({
+  kind: z.enum(["next", "vite", "html", "empty", "other"]).optional(),
+  name: z.string().max(200).optional(),
+  summary: z.string().max(800).optional(),
+  scripts: z.object({
+    ui: z.string().min(1).max(64).optional(),
+    backend: z.string().min(1).max(64).optional(),
+    app: z.string().min(1).max(64).optional()
+  }).optional(),
+  ports: z.object({
+    ui: z.number().int().min(1).max(65535).optional(),
+    backend: z.number().int().min(1).max(65535).optional(),
+    app: z.number().int().min(1).max(65535).optional()
+  }).optional(),
+  issues: z.array(z.string().max(500)).max(20).optional(),
+  fixes: z.array(z.string().max(500)).max(20).optional(),
+  ready: z.boolean().optional()
+});
+function extractInspectJson(text) {
+  const fence = text.match(/```json\s*([\s\S]*?)```/i);
+  const raw = fence?.[1]?.trim() || text.match(/\{[\s\S]*\}/)?.[0];
+  if (!raw) return null;
+  try {
+    const parsed = inspectJsonSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+function setupSystemPrompt(input) {
+  return `You are Maintainer Pro's local setup assistant on the developer's machine.
+
+Workspace: ${input.workspaceDir}
+App name: ${input.appName || "the app"}
+
+Inspect this repository (package.json, README, lockfiles, existing env files, how the UI and API start).
+You MAY edit files to fix setup problems that would block local run or the chat widget (env keys, widget mount, missing config).
+Do NOT start long-lived dev servers, tunnels, or install global tools.
+Do NOT run \`npm run dev\` or similar.
+
+Script names you report MUST already exist in package.json. Omit chat/ai-server scripts.
+
+End 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": ["remaining problems"],
+  "fixes": ["what you changed"],
+  "ready": true
+}`;
+}
+function setupUserMessage(input) {
+  if (input.problem?.trim()) {
+    return `The local bridge failed to keep this project running:
+
+${input.problem.trim()}
+
+${input.extraContext ? `${input.extraContext.trim()}
+
+` : ""}Inspect the repo, fix the cause if you can, and return the JSON report.`;
+  }
+  return `${input.extraContext ? `${input.extraContext.trim()}
+
+` : ""}Inspect this project, fix any setup gaps you can, and return the JSON report.`;
+}
+async function inspectAndRepairWorkspace(input) {
+  const workspaceDir = input.workspaceDir;
+  const provider = await resolveProvider({ preference: "auto" });
+  const response = await callAi(
+    [{ role: "user", content: setupUserMessage(input) }],
+    {
+      route: "/local-setup",
+      pageTitle: input.appName || "Local setup",
+      relevantFiles: ["package.json", "README.md", ".env", ".env.example"],
+      data: {
+        workspaceDir,
+        problem: input.problem || null
+      }
+    },
+    {
+      systemPrompt: setupSystemPrompt(input),
+      workspaceDir,
+      technical: true
+    }
+  );
+  const parsed = extractInspectJson(response.text);
+  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
+  };
 }
 export {
+  ACCESS_IGNORE_BEGIN,
+  ACCESS_IGNORE_END,
+  DEFAULT_AI_IGNORE_PATHS,
+  PROMPT_SECTION,
   WORKING_PROVIDER,
   buildClaudeUserPrompt,
   buildConversationPrompt,
   buildCursorPrompt,
   buildPriorConversationsContext,
   callAi,
+  collectParentChain,
   commandExists,
   createAntigravityProvider,
   createBuiltinProviders,
@@ -1096,16 +2409,34 @@ export {
   createClaudeProvider,
   createCursorProvider,
   createDefaultSystemPrompt,
+  createInfoLogger,
   createLocalDirectoryStore,
+  createLogger,
   createMaintainerProStore,
   createMaintainerProStoreFromEnv,
+  createSyncedChatStore,
   createToolValidator,
+  formatAccessPolicyPromptSection,
   formatClientContext,
+  formatParentChainContext,
   getProviderPreference,
+  inspectAndRepairWorkspace,
+  isDevMode,
+  isIgnoredRelative,
+  isInsideWorkspace,
+  isPathAllowed,
+  normalizeIgnorePaths,
+  parentChainForTurn,
   parseAiResponse,
+  parseIgnorePathsEnv,
+  previewText,
   providerLabel,
+  renderManagedIgnoreBlock,
   resolveCliBinary,
+  resolveIgnorePaths,
+  resolveLogLevel,
   resolveProvider,
   saveChatAttachments,
-  toNextRoute
+  toNextRoute,
+  upsertManagedIgnoreFile
 };