opencandle 0.10.0 → 0.11.1

package/gui/server/http-routes.ts

@@ -3,12 +3,35 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { extname, join, resolve } from "node:path";
 import { type AgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
 import { buildDoctorReport } from "../../src/doctor/report.js";
+import { MarketStateService } from "../../src/market-state/service.js";
+import {
+  formatLatestReportSummary,
+  formatPortfolioSummary,
+  formatWatchlistSummary,
+} from "../../src/market-state/summaries.js";
+import { initDefaultDatabase } from "../../src/memory/sqlite.js";
 import { probeProviderStatus } from "../../src/onboarding/provider-status.js";
+import {
+  clearPendingSessionAction,
+  hasAcceptedSessionAction,
+  hasPendingSessionAction,
+  recordAcceptedSessionAction,
+  recordPendingSessionAction,
+} from "../../src/pi/session-action-dedupe.js";
 import type { ChatEvent } from "../shared/chat-events.js";
 import { sessionEntriesToChatEvents } from "./chat-event-adapter.js";
-import { chatRunSessionConflict } from "./chat-run-session.js";
+import type { ToolInvokeController } from "./invoke-tool.js";
 import { createLiveChatEventAdapter } from "./live-chat-event-adapter.js";
-import { buildMarketStateSnapshot, searchInstrumentCandidates } from "./market-state-api.js";
+import type {
+  LocalSessionCoordinator,
+  SessionActionEnvelope,
+  SessionActionResult,
+} from "./local-session-coordinator.js";
+import {
+  buildMarketStateSnapshot,
+  getSavedMarketStateSymbols,
+  searchInstrumentCandidates,
+} from "./market-state-api.js";
 import { buildModelSetupState, type ModelSetupController } from "./model-setup.js";
 import { isTrustedPrivateApiRequest, privateApiCookieHeader } from "./private-api-access.js";
 import { projectDashboard } from "./projector.js";
@@ -19,9 +42,11 @@ import { waitForNewEntryId } from "./session-entry-wait.js";
 import { buildCatalog } from "./tool-metadata.js";
 import {
   acquireWriterLock,
+  isCoordinatorOwnerAlive,
   readWriterLock,
   refreshWriterLock,
   releaseWriterLock,
+  shouldBlockFailedCoordinatorAction as shouldBlockFailedCoordinatorLockAction,
   writerLockScopeForSession,
 } from "./writer-lock.js";
 import type { WsHub } from "./ws-hub.js";
@@ -35,16 +60,43 @@ interface GuiHttpRouteOptions {
   agentDir: string;
   sessionDir: string;
   privateApiSessionToken: string;
+  localCoordinatorEndpoint: string;
+  localCoordinatorSecret: string;
   allowRemotePrivateApi: boolean;
+  syncCurrentWriterLockScope?: () => void;
   getSession: () => AgentSession;
   getSessionManager: () => SessionManager;
   createSessionForManager: (sessionManager: SessionManager) => Promise<{ session: AgentSession }>;
   wsHub: WsHub;
   modelSetupController: ModelSetupController;
   sessionActionsController: SessionActionsController;
+  toolInvokeController: ToolInvokeController;
   quoteSnapshotStore: QuoteSnapshotStore;
+  localSessionCoordinator?: LocalSessionCoordinator;
 }
 
+export interface ChatRunImageInput {
+  data: string;
+  mimeType: string;
+}
+
+export type ChatRunAttachmentInput =
+  | { kind: "portfolio"; id?: string }
+  | { kind: "watchlist"; id: string }
+  | { kind: "report"; id: string };
+
+export interface ParsedChatRunBody {
+  prompt: string;
+  images: ChatRunImageInput[];
+  attachments: ChatRunAttachmentInput[];
+}
+
+type ChatRunParseResult = { ok: true; value: ParsedChatRunBody } | { ok: false; error: string };
+
+const CHAT_RUN_IMAGE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/webp"]);
+const CHAT_RUN_MAX_IMAGE_COUNT = 4;
+const CHAT_RUN_MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+
 export function createHttpRequestHandler(options: GuiHttpRouteOptions) {
   const activeRunSessionIds = new Set<string>();
 
@@ -67,7 +119,11 @@ export function createHttpRequestHandler(options: GuiHttpRouteOptions) {
     if (url.pathname === "/api/session/new" && req.method === "POST") {
       if (!allowTrustedGuiRequest(req, res, "Session API", options)) return;
       if (options.role !== "writer") {
-        writeJson(res, { error: "Read-only follower mode" }, 409);
+        writeJson(
+          res,
+          { error: "OpenCandle is reconnecting to this session.", code: "syncing" },
+          409,
+        );
         return;
       }
       await options.sessionActionsController.handleNewSession();
@@ -211,19 +267,109 @@ export function createHttpRequestHandler(options: GuiHttpRouteOptions) {
 
     if (url.pathname === "/api/chat/run" && req.method === "POST") {
       if (!allowTrustedGuiRequest(req, res, "Chat run API", options)) return;
-      await handleSseChatRun(req, res, options, activeRunSessionIds);
+      writeJson(
+        res,
+        {
+          error: "Legacy active-session chat runs are no longer supported.",
+          code: "legacy_route_removed",
+        },
+        410,
+      );
+      return;
+    }
+
+    if (url.pathname === "/api/local-coordinator/chat-run" && req.method === "POST") {
+      if (!allowLocalCoordinatorRequest(req, res, options)) return;
+      const body = asRecord(await readJsonBody(req));
+      if (!requireSessionActionFields(res, body)) return;
+      const sessionManager = await resolveSessionManagerById(options, String(body.sessionId));
+      if (!sessionManager) {
+        writeJson(res, { error: "Unknown saved session" }, 404);
+        return;
+      }
+      // allowProxy: false — this endpoint is the proxy target; re-proxying loops.
+      await handleSseChatRun(req, res, options, activeRunSessionIds, sessionManager, body, false);
+      return;
+    }
+
+    if (url.pathname === "/api/local-coordinator/tool-invoke" && req.method === "POST") {
+      if (!allowLocalCoordinatorRequest(req, res, options)) return;
+      const body = asRecord(await readJsonBody(req));
+      if (!requireSessionActionFields(res, body)) return;
+      let ack: unknown;
+      await options.toolInvokeController.handleToolInvokeMessage(
+        { send: (message) => (ack = message) },
+        {
+          requestId: "local-coordinator-tool",
+          actionId: String(body.actionId ?? ""),
+          sessionId: String(body.sessionId ?? ""),
+          toolName: String(body.toolName ?? ""),
+          args: asRecord(body.args),
+          allowProxy: false,
+        },
+      );
+      const message = asRecord(ack);
+      const result = asRecord(message.result);
+      if (result.toolCallId) {
+        writeJson(res, { result });
+      } else {
+        writeJson(
+          res,
+          { error: String(asRecord(message.error).message ?? "Tool invocation failed") },
+          409,
+        );
+      }
+      return;
+    }
+
+    if (url.pathname === "/api/local-coordinator/ask-user" && req.method === "POST") {
+      if (!allowLocalCoordinatorRequest(req, res, options)) return;
+      const body = asRecord(await readJsonBody(req));
+      if (!requireSessionActionFields(res, body)) return;
+      const payload = asRecord(body.payload);
+      try {
+        const action = {
+          actionId: String(body.actionId ?? ""),
+          sessionId: String(body.sessionId ?? ""),
+          source: "browser" as const,
+          allowProxy: false,
+        };
+        if (body.actionType === "ask_user.answer") {
+          await options.sessionActionsController.handleAskUserAnswer(
+            String(payload.id ?? ""),
+            payload.answer,
+            action,
+          );
+        } else if (body.actionType === "ask_user.cancel") {
+          await options.sessionActionsController.handleAskUserCancel(
+            String(payload.id ?? ""),
+            action,
+          );
+        } else {
+          writeJson(res, { error: "Unknown ask_user action" }, 400);
+          return;
+        }
+        writeJson(res, { ok: true });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeJson(res, { error: message }, 409);
+      }
       return;
     }
 
     const runSessionId = sessionIdFromRoute(url.pathname, "runs");
     if (runSessionId && req.method === "POST") {
       if (!allowTrustedGuiRequest(req, res, "Chat run API", options)) return;
+      const body = asRecord(await readJsonBody(req));
+      if (!requireSessionActionFields(res, { ...body, sessionId: runSessionId }, false)) return;
       const sessionManager = await resolveSessionManagerById(options, runSessionId);
       if (!sessionManager) {
         writeJson(res, { error: "Unknown saved session" }, 404);
         return;
       }
-      await handleSseChatRun(req, res, options, activeRunSessionIds, sessionManager);
+      // allowProxy: true — forward to a live coordinator owned by another
+      // process (0.11.0 authenticated local forwarding).
+      await handleSseChatRun(req, res, options, activeRunSessionIds, sessionManager, body, true);
       return;
     }
 
@@ -236,31 +382,26 @@ async function handleSseChatRun(
   res: ServerResponse,
   options: GuiHttpRouteOptions,
   activeRunSessionIds: Set<string>,
-  targetSessionManager?: SessionManager,
+  targetSessionManager: SessionManager | undefined,
+  bodyOverride: Record<string, unknown> | undefined,
+  // Explicit because both remaining callers pass a body: the browser-facing
+  // runs route must forward to a live coordinator owned by another process,
+  // while the local-coordinator endpoint IS the proxy target and re-proxying
+  // there would loop.
+  allowProxy: boolean,
 ): Promise<void> {
-  if (options.role !== "writer") {
-    writeJson(res, { error: "Read-only follower mode" }, 409);
+  const body = bodyOverride ?? asRecord(await readJsonBody(req));
+  const parsed = parseChatRunBody(body);
+  if (!parsed.ok) {
+    writeJson(res, { error: parsed.error }, 400);
     return;
   }
-
-  const body = await readJsonBody(req);
-  const prompt = String(asRecord(body).prompt ?? "").trim();
-  if (!prompt) {
-    writeJson(res, { error: "prompt is required" }, 400);
-    return;
-  }
-
   const currentSessionManager = options.getSessionManager();
-  const requestedSessionId = String(asRecord(body).sessionId ?? "").trim();
+  const bodyRecord = asRecord(body);
+  const requestedSessionId = String(bodyRecord.sessionId ?? "").trim();
   const runSessionManager = targetSessionManager ?? currentSessionManager;
   const sessionId = runSessionManager.getSessionId();
-  if (!targetSessionManager) {
-    const sessionConflict = chatRunSessionConflict(requestedSessionId, sessionId);
-    if (sessionConflict) {
-      writeJson(res, sessionConflict, 409);
-      return;
-    }
-  } else if (requestedSessionId && requestedSessionId !== sessionId) {
+  if (requestedSessionId && requestedSessionId !== sessionId) {
     writeJson(
       res,
       { error: "Session route and request body disagree", code: "session_changed" },
@@ -269,22 +410,212 @@ async function handleSseChatRun(
     return;
   }
 
+  const actionId = String(bodyRecord.actionId ?? "").trim();
+  const shouldProxyChatRun = allowProxy && canProxyChatRunToCoordinator(runSessionManager);
+  if (shouldProxyChatRun) {
+    if (await proxyChatRunToCoordinator(res, runSessionManager, bodyRecord)) {
+      const useCurrentSession =
+        !targetSessionManager ||
+        currentSessionManager.getSessionFile() === runSessionManager.getSessionFile();
+      await broadcastFreshRunSessionSnapshot(options, runSessionManager, useCurrentSession);
+      return;
+    }
+    if (actionId && hasAcceptedSessionAction(runSessionManager, actionId)) {
+      writeJson(res, { ok: true, duplicate: true });
+      return;
+    }
+    if (actionId && hasPendingSessionAction(runSessionManager, actionId)) {
+      writeJson(
+        res,
+        { error: "OpenCandle is reconnecting to this session.", code: "syncing" },
+        409,
+      );
+      return;
+    }
+    if (shouldBlockFailedCoordinatorAction(runSessionManager, bodyRecord)) {
+      writeJson(
+        res,
+        { error: "OpenCandle is reconnecting to this session.", code: "syncing" },
+        409,
+      );
+      return;
+    }
+  }
+  if (actionId && hasAcceptedSessionAction(runSessionManager, actionId)) {
+    writeJson(res, { ok: true, duplicate: true });
+    return;
+  }
+  if (actionId && hasPendingSessionAction(runSessionManager, actionId)) {
+    writeJson(res, { error: "OpenCandle is reconnecting to this session.", code: "syncing" }, 409);
+    return;
+  }
+
+  if (options.localSessionCoordinator) {
+    const action = buildChatRunActionEnvelope(bodyRecord, sessionId);
+    let result: SessionActionResult<{ streamed: boolean }>;
+    try {
+      result = await options.localSessionCoordinator.runSessionAction(action, async () => {
+        const admitted = await streamAcceptedSseChatRun({
+          res,
+          options,
+          activeRunSessionIds,
+          targetSessionManager,
+          currentSessionManager,
+          runSessionManager,
+          sessionId,
+          parsedRun: parsed.value,
+          actionId: action.actionId,
+        });
+        if (!admitted) throw new SessionActionNotAdmitted();
+        return { streamed: true };
+      });
+    } catch (error) {
+      if (error instanceof SessionActionNotAdmitted) return;
+      throw error;
+    }
+    if (!result.ok) {
+      writeJson(res, { error: result.message, code: result.code }, 409);
+      return;
+    }
+    if (result.duplicate && !res.headersSent) {
+      writeJson(res, { ok: true, duplicate: true });
+    }
+    return;
+  }
+
+  await streamAcceptedSseChatRun({
+    res,
+    options,
+    activeRunSessionIds,
+    targetSessionManager,
+    currentSessionManager,
+    runSessionManager,
+    sessionId,
+    parsedRun: parsed.value,
+    actionId,
+  });
+}
+
+export function canProxyChatRunToCoordinator(runSessionManager: SessionManager): boolean {
+  const lock = readWriterLock(writerLockScopeForSession(runSessionManager));
+  return hasLiveCoordinatorLock(lock);
+}
+
+async function proxyChatRunToCoordinator(
+  res: ServerResponse,
+  runSessionManager: SessionManager,
+  body: Record<string, unknown>,
+): Promise<boolean> {
+  const lock = readWriterLock(writerLockScopeForSession(runSessionManager));
+  if (!hasLiveCoordinatorLock(lock)) return false;
+  const endpoint = new URL("/api/local-coordinator/chat-run", lock.coordinatorEndpoint);
+  let response: Response;
+  try {
+    response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-opencandle-coordinator-secret": lock.coordinatorSecret,
+      },
+      body: JSON.stringify({ ...body, sessionId: runSessionManager.getSessionId() }),
+    });
+  } catch {
+    return false;
+  }
+  res.writeHead(response.status, Object.fromEntries(response.headers));
+  if (response.body) {
+    for await (const chunk of response.body) {
+      res.write(chunk);
+    }
+  }
+  res.end();
+  return true;
+}
+
+function hasLiveCoordinatorLock(
+  lock: ReturnType<typeof readWriterLock>,
+  staleGraceMs = 15_000,
+): lock is NonNullable<ReturnType<typeof readWriterLock>> & {
+  coordinatorEndpoint: string;
+  coordinatorSecret: string;
+} {
+  if (!lock?.coordinatorEndpoint || !lock.coordinatorSecret || lock.pid === process.pid) {
+    return false;
+  }
+  const heartbeat = Date.parse(lock.lastHeartbeat);
+  const hasFreshHeartbeat = Number.isFinite(heartbeat) && Date.now() - heartbeat <= staleGraceMs;
+  return hasFreshHeartbeat && isCoordinatorOwnerAlive(lock.pid);
+}
+
+async function streamAcceptedSseChatRun({
+  res,
+  options,
+  activeRunSessionIds,
+  targetSessionManager,
+  currentSessionManager,
+  runSessionManager,
+  sessionId,
+  parsedRun,
+  actionId,
+}: {
+  res: ServerResponse;
+  options: GuiHttpRouteOptions;
+  activeRunSessionIds: Set<string>;
+  targetSessionManager?: SessionManager;
+  currentSessionManager: SessionManager;
+  runSessionManager: SessionManager;
+  sessionId: string;
+  parsedRun: ParsedChatRunBody;
+  actionId: string;
+}): Promise<boolean> {
+  const prompt = parsedRun.prompt;
   if (activeRunSessionIds.has(sessionId)) {
     writeJson(res, { error: "Session already has an active run", code: "session_busy" }, 409);
-    return;
+    return false;
+  }
+  let dispatchedPrompt: string;
+  try {
+    dispatchedPrompt = await buildDispatchedPrompt(parsedRun);
+  } catch (error) {
+    writeJson(res, { error: error instanceof Error ? error.message : String(error) }, 400);
+    return false;
   }
+  const promptImages = parsedRun.images.map((image) => ({
+    type: "image" as const,
+    data: image.data,
+    mimeType: image.mimeType,
+  }));
+  const attachmentLabels = parsedRun.attachments.map((attachment) => ({
+    kind: attachment.kind,
+    label: attachmentLabel(attachment),
+  }));
+  const inputAttachmentLabels = [
+    ...promptImages.map((image, index) => ({
+      kind: "image",
+      label: `${image.mimeType || "image"} #${index + 1}`,
+    })),
+    ...attachmentLabels,
+  ];
 
   const currentSessionFile = currentSessionManager.getSessionFile();
   const targetSessionFile = runSessionManager.getSessionFile();
   const useCurrentSession = !targetSessionManager || currentSessionFile === targetSessionFile;
   let acquiredLockScope = "";
   let lockHeartbeat: ReturnType<typeof setInterval> | undefined;
-  if (!useCurrentSession) {
+  const needsWriterLock = !useCurrentSession || options.role !== "writer";
+  if (needsWriterLock) {
     const lockScope = writerLockScopeForSession(runSessionManager);
-    const lockResult = await acquireWriterLock(lockScope, "gui");
+    const lockResult = await acquireWriterLock(lockScope, "gui", {
+      coordinatorEndpoint: options.localCoordinatorEndpoint,
+      coordinatorSecret: options.localCoordinatorSecret,
+    });
     if (lockResult.role !== "writer") {
-      writeJson(res, { error: "Read-only follower mode", lock: lockResult.lock }, 409);
-      return;
+      writeJson(
+        res,
+        { error: "OpenCandle is reconnecting to this session.", code: "syncing" },
+        409,
+      );
+      return false;
     }
     acquiredLockScope = lockScope;
     lockHeartbeat = setInterval(() => refreshWriterLock(lockScope), 5000);
@@ -302,7 +633,7 @@ async function handleSseChatRun(
     if (acquiredLockScope) releaseWriterLock(acquiredLockScope);
     const message = error instanceof Error ? error.message : String(error);
     writeJson(res, { error: message }, 500);
-    return;
+    return false;
   }
 
   res.writeHead(200, {
@@ -329,17 +660,45 @@ async function handleSseChatRun(
     startSeq: seq,
     emit: (event) => writeSse(res, event),
     originalPrompt: prompt,
+    originalAttachments: inputAttachmentLabels,
   });
   const observation = createPromptObservation();
+  let originalInputMarkerAppended = false;
+  const appendOriginalInputMarker = () => {
+    if (inputAttachmentLabels.length === 0 || originalInputMarkerAppended) return;
+    runSessionManager.appendCustomEntry("opencandle-user-input", {
+      original: prompt,
+      attachments: inputAttachmentLabels,
+    });
+    originalInputMarkerAppended = true;
+  };
+  let actionAccepted = false;
+  const recordAcceptedAction = () => {
+    if (actionAccepted) return;
+    appendOriginalInputMarker();
+    recordAcceptedSessionAction(runSessionManager, actionId);
+    if (useCurrentSession) options.syncCurrentWriterLockScope?.();
+    actionAccepted = true;
+  };
+
   const unsubscribeLive = runSession.subscribe((event) => {
     liveAdapter.handle(event);
     observePromptEvent(observation, event);
+    if (
+      !prompt.startsWith("/") &&
+      !actionAccepted &&
+      observation.userTexts.some((text) => text.trim() === dispatchedPrompt.trim())
+    ) {
+      recordAcceptedAction();
+    }
   });
 
   try {
+    recordPendingSessionAction(runSessionManager, actionId);
     const modelSetup = buildModelSetupState(runSession.modelRegistry, runSession.model);
     if (!prompt.startsWith("/") && modelSetup.requirement !== "ready") {
       runSessionManager.appendMessage({ role: "user", content: prompt, timestamp: Date.now() });
+      recordAcceptedAction();
       const message =
         modelSetup.requirement === "select_model"
           ? "Choose an available model before chat can run. OpenCandle found configured credentials but no active model."
@@ -348,10 +707,17 @@ async function handleSseChatRun(
         source: "gui",
         requirement: modelSetup.requirement,
       });
-      broadcastRunSessionSnapshot(options, runSessionManager, useCurrentSession);
+      await broadcastRunSessionSnapshot(options, runSessionManager, useCurrentSession);
     } else {
-      await promptAndSettle(runSession, prompt, beforeIds, observation);
-      broadcastRunSessionSnapshot(options, runSessionManager, useCurrentSession);
+      await promptAndSettle(
+        runSession,
+        dispatchedPrompt,
+        beforeIds,
+        observation,
+        promptImages.length > 0 ? { images: promptImages } : undefined,
+      );
+      recordAcceptedAction();
+      await broadcastRunSessionSnapshot(options, runSessionManager, useCurrentSession);
     }
     seq = liveAdapter.nextSeq();
     if (seq === liveStartSeq) {
@@ -375,6 +741,7 @@ async function handleSseChatRun(
     }
     writeSse(res, { type: "run.completed", runId, sessionId, seq });
   } catch (error) {
+    if (!actionAccepted) clearPendingSessionAction(runSessionManager, actionId);
     seq = liveAdapter.nextSeq();
     const message = error instanceof Error ? error.message : String(error);
     writeSse(res, { type: "run.failed", runId, sessionId, error: { message }, seq });
@@ -386,14 +753,18 @@ async function handleSseChatRun(
     if (acquiredLockScope) releaseWriterLock(acquiredLockScope);
     res.end();
   }
+  return actionAccepted;
 }
 
-function broadcastRunSessionSnapshot(
+class SessionActionNotAdmitted extends Error {}
+
+async function broadcastRunSessionSnapshot(
   options: GuiHttpRouteOptions,
   sessionManager: SessionManager,
   useCurrentSession: boolean,
-): void {
+): Promise<void> {
   if (useCurrentSession) {
+    options.syncCurrentWriterLockScope?.();
     options.wsHub.broadcastState();
   } else {
     options.wsHub.broadcastSessionSnapshot(sessionManager);
@@ -401,6 +772,51 @@ function broadcastRunSessionSnapshot(
   }
 }
 
+async function broadcastFreshRunSessionSnapshot(
+  options: GuiHttpRouteOptions,
+  sessionManager: SessionManager,
+  useCurrentSession: boolean,
+): Promise<void> {
+  const freshSessionManager = await reloadSessionManager(sessionManager, options);
+  if (useCurrentSession) {
+    options.syncCurrentWriterLockScope?.();
+    options.wsHub.broadcast({
+      type: "state.snapshot",
+      ...buildSnapshotPayload(freshSessionManager),
+    });
+  } else {
+    options.wsHub.broadcast({
+      type: "session.snapshot",
+      ...buildSnapshotPayload(freshSessionManager),
+    });
+    options.wsHub.broadcastSessions();
+  }
+}
+
+async function reloadSessionManager(
+  sessionManager: SessionManager,
+  options: Pick<GuiHttpRouteOptions, "sessionDir" | "cwd">,
+): Promise<SessionManager> {
+  const sessionFile = sessionManager.getSessionFile();
+  return sessionFile
+    ? SessionManager.open(sessionFile, options.sessionDir, options.cwd)
+    : sessionManager;
+}
+
+function buildSnapshotPayload(sessionManager: SessionManager): Record<string, unknown> {
+  const sessionId = sessionManager.getSessionId();
+  const entries = sessionManager.getEntries();
+  return {
+    sessionId,
+    state: projectDashboard(entries, sessionId, getSavedMarketStateSymbols()),
+    entries,
+    events: sessionEntriesToChatEvents(entries, {
+      sessionId,
+      title: sessionManager.getSessionName(),
+    }),
+  };
+}
+
 export async function buildSessionBootstrapPayload(
   options: Pick<
     GuiHttpRouteOptions,
@@ -414,13 +830,18 @@ export async function buildSessionBootstrapPayload(
   return {
     role: roleForSessionBootstrap(options, sessionManager),
     sessionId,
+    coordination: {
+      sessionId,
+      status: roleForSessionBootstrap(options, sessionManager) === "writer" ? "ready" : "syncing",
+      ownerKind: ownerKindForSessionBootstrap(options, sessionManager),
+    },
     catalog: buildCatalog(),
     modelSetup: options.modelSetupController.buildCurrentModelSetupState(),
     askUserPrompts: Array.isArray(bootstrap.askUserPrompts) ? bootstrap.askUserPrompts : [],
     sessions: await SessionManager.list(options.cwd, options.sessionDir),
     snapshot: {
       sessionId,
-      state: projectDashboard(entries, sessionId),
+      state: projectDashboard(entries, sessionId, getSavedMarketStateSymbols()),
       entries,
       events: sessionEntriesToChatEvents(entries, {
         sessionId,
@@ -430,6 +851,14 @@ export async function buildSessionBootstrapPayload(
   };
 }
 
+function ownerKindForSessionBootstrap(
+  options: Pick<GuiHttpRouteOptions, "getSessionManager" | "role">,
+  sessionManager: SessionManager,
+): string | undefined {
+  if (roleForSessionBootstrap(options, sessionManager) === "writer") return "gui";
+  return readWriterLock(writerLockScopeForSession(sessionManager))?.processKind;
+}
+
 function roleForSessionBootstrap(
   options: Pick<GuiHttpRouteOptions, "role" | "getSessionManager">,
   sessionManager: SessionManager,
@@ -462,6 +891,180 @@ export function sessionIdFromRoute(pathname: string, action: "bootstrap" | "runs
   }
 }
 
+export function buildChatRunActionEnvelope(
+  body: Record<string, unknown>,
+  sessionId: string,
+): SessionActionEnvelope {
+  const actionId = String(body.actionId ?? "").trim();
+  const parsed = parseChatRunBody(body);
+  const attachments = parsed.ok ? parsed.value.attachments : [];
+  const images = parsed.ok ? parsed.value.images : [];
+  return {
+    sessionId,
+    actionId,
+    actionType: "chat.prompt",
+    payload: {
+      prompt: String(body.prompt ?? ""),
+      ...(images.length > 0 ? { imageCount: images.length } : {}),
+      ...(attachments.length > 0
+        ? { attachments: attachments.map((attachment) => ({ kind: attachment.kind })) }
+        : {}),
+    },
+    source: "browser",
+  };
+}
+
+export function parseChatRunBody(body: unknown): ChatRunParseResult {
+  const record = asRecord(body);
+  const prompt = String(record.prompt ?? "").trim();
+  if (!prompt) return { ok: false, error: "prompt is required" };
+
+  const rawImages = record.images;
+  const images: ChatRunImageInput[] = [];
+  if (rawImages !== undefined) {
+    if (!Array.isArray(rawImages)) return { ok: false, error: "images must be an array" };
+    if (rawImages.length > CHAT_RUN_MAX_IMAGE_COUNT) {
+      return { ok: false, error: "Attach up to 4 images" };
+    }
+    for (const rawImage of rawImages) {
+      const image = asRecord(rawImage);
+      const mimeType = String(image.mimeType ?? "");
+      const data = String(image.data ?? "");
+      if (!CHAT_RUN_IMAGE_MIME_TYPES.has(mimeType)) {
+        return { ok: false, error: "Unsupported image mime type" };
+      }
+      if (data.length > Math.ceil(CHAT_RUN_MAX_IMAGE_BYTES / 3) * 4) {
+        return { ok: false, error: "Image attachment must be 5 MB or smaller" };
+      }
+      const decoded = decodeStrictBase64(data);
+      if (!decoded) {
+        return { ok: false, error: "Image attachment data must be valid base64" };
+      }
+      if (decoded.byteLength > CHAT_RUN_MAX_IMAGE_BYTES) {
+        return { ok: false, error: "Image attachment must be 5 MB or smaller" };
+      }
+      images.push({ data, mimeType });
+    }
+  }
+
+  const rawAttachments = record.attachments;
+  const attachments: ChatRunAttachmentInput[] = [];
+  if (rawAttachments !== undefined) {
+    if (!Array.isArray(rawAttachments)) {
+      return { ok: false, error: "attachments must be an array" };
+    }
+    for (const rawAttachment of rawAttachments) {
+      const attachment = asRecord(rawAttachment);
+      const kind = String(attachment.kind ?? "");
+      const id = typeof attachment.id === "string" ? attachment.id.trim() : "";
+      if (kind === "portfolio") {
+        attachments.push(id ? { kind, id } : { kind });
+      } else if (kind === "watchlist" || kind === "report") {
+        if (!id) return { ok: false, error: `${kind} attachment id is required` };
+        attachments.push({ kind, id });
+      } else {
+        return { ok: false, error: "Unsupported attachment kind" };
+      }
+    }
+  }
+
+  if (prompt.startsWith("/") && (images.length > 0 || attachments.length > 0)) {
+    return { ok: false, error: "Attachments are not supported for slash commands" };
+  }
+
+  return { ok: true, value: { prompt, images, attachments } };
+}
+
+function decodeStrictBase64(data: string): Buffer | null {
+  if (!data || data.trim() !== data) return null;
+  if (data.length % 4 !== 0) return null;
+  if (/[^A-Za-z0-9+/=]/.test(data)) return null;
+  const firstPadding = data.indexOf("=");
+  if (firstPadding !== -1) {
+    const padding = data.slice(firstPadding);
+    if (!/^={1,2}$/.test(padding)) return null;
+  }
+  const decoded = Buffer.from(data, "base64");
+  if (decoded.byteLength === 0) return null;
+  return decoded.toString("base64") === data ? decoded : null;
+}
+
+export async function buildDispatchedPrompt(parsed: ParsedChatRunBody): Promise<string> {
+  if (parsed.prompt.startsWith("/")) return parsed.prompt;
+  if (parsed.attachments.length === 0) return parsed.prompt;
+  const db = initDefaultDatabase();
+  try {
+    const service = new MarketStateService(db);
+    const blocks = parsed.attachments.map((attachment) => {
+      const lines = attachmentSummaryLines(service, attachment);
+      if (lines.length === 0) throw new Error(`${attachment.kind} attachment was empty`);
+      return `[Attached by user — ${attachment.kind}]\n${lines.join("\n")}`;
+    });
+    return [parsed.prompt, ...blocks].join("\n\n");
+  } finally {
+    db.close();
+  }
+}
+
+function attachmentSummaryLines(
+  service: MarketStateService,
+  attachment: ChatRunAttachmentInput,
+): string[] {
+  if (attachment.kind === "portfolio") {
+    const portfolioId = attachment.id ? Number(attachment.id) : undefined;
+    if (attachment.id && !Number.isFinite(portfolioId)) {
+      throw new Error("Unknown portfolio attachment");
+    }
+    return formatPortfolioSummary(service.listPortfolioLots(portfolioId));
+  }
+  if (attachment.kind === "watchlist") {
+    const watchlistId =
+      attachment.id === "default" ? service.getDefaultWatchlist().id : Number(attachment.id);
+    if (!Number.isFinite(watchlistId)) throw new Error("Unknown watchlist attachment");
+    return formatWatchlistSummary(service.listWatchlistItems(watchlistId));
+  }
+  const reports = service.listReportRuns();
+  const report =
+    attachment.id === "latest"
+      ? reports[0]
+      : reports.find((candidate) => candidate.id === Number(attachment.id));
+  if (!report) throw new Error("Unknown report attachment");
+  return formatLatestReportSummary(report);
+}
+
+function attachmentLabel(attachment: ChatRunAttachmentInput): string {
+  if (attachment.kind === "portfolio") return "Portfolio";
+  if (attachment.kind === "watchlist") return "Watchlist";
+  return "Latest report";
+}
+
+function hasClientActionId(body: Record<string, unknown>): boolean {
+  return typeof body.actionId === "string" && body.actionId.trim().length > 0;
+}
+
+function requireSessionActionFields(
+  res: ServerResponse,
+  body: Record<string, unknown>,
+  requireSessionId = true,
+): boolean {
+  if (requireSessionId && !String(body.sessionId ?? "").trim()) {
+    writeJson(res, { error: "sessionId is required" }, 400);
+    return false;
+  }
+  if (!String(body.actionId ?? "").trim()) {
+    writeJson(res, { error: "actionId is required" }, 400);
+    return false;
+  }
+  return true;
+}
+
+function shouldBlockFailedCoordinatorAction(
+  runSessionManager: SessionManager,
+  body: Record<string, unknown>,
+): boolean {
+  return hasClientActionId(body) && shouldBlockFailedCoordinatorLockAction(runSessionManager);
+}
+
 async function handleTrustedGuiMutation(
   req: IncomingMessage,
   res: ServerResponse,
@@ -473,7 +1076,15 @@ async function handleTrustedGuiMutation(
     writeJson(res, await options.wsHub.buildBootstrapPayload());
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    writeJson(res, { error: message }, message === "Read-only follower mode" ? 409 : 400);
+    const coordinationError = message === "Read-only follower mode";
+    writeJson(
+      res,
+      {
+        error: coordinationError ? "OpenCandle is reconnecting to this session." : message,
+        ...(coordinationError ? { code: "syncing" } : {}),
+      },
+      coordinationError ? 409 : 400,
+    );
   }
 }
 
@@ -531,6 +1142,19 @@ function allowTrustedGuiRequest(
   return false;
 }
 
+function allowLocalCoordinatorRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  options: GuiHttpRouteOptions,
+): boolean {
+  if (req.headers["x-opencandle-coordinator-secret"] === options.localCoordinatorSecret) {
+    return true;
+  }
+  res.writeHead(403, { "content-type": "application/json" });
+  res.end(JSON.stringify({ error: "Local coordinator request was not authorized." }));
+  return false;
+}
+
 function privateGuiHeaders(
   contentTypeValue: string,
   options: GuiHttpRouteOptions,