flockbay 0.10.27 → 0.10.30

package/dist/{index-D7iB7SzL.mjs → index-DGp07Mik.mjs}

@@ -1,14 +1,14 @@
 import{createRequire as _pkgrollCR}from"node:module";const require=_pkgrollCR(import.meta.url);import chalk from 'chalk';
 import os, { homedir } from 'node:os';
 import { randomUUID, createCipheriv, randomBytes } from 'node:crypto';
-import { l as logger, p as projectPath, d as backoff, e as delay, R as RawJSONLinesSchema, c as configuration, f as readDaemonState, g as clearDaemonState, b as packageJson, r as readSettings, h as readCredentials, u as updateSettings, w as writeCredentials, i as unrealMcpPythonDir, j as acquireDaemonLock, k as writeDaemonState, m as ApiMachineClient, n as releaseDaemonLock, s as sendUnrealMcpTcpCommand, A as ApiClient, o as clearCredentials, q as clearMachineId, t as installUnrealMcpPluginToEngine, v as buildAndInstallUnrealMcpPlugin, x as getLatestDaemonLog, y as normalizeServerUrlForNode } from './types-DYcgk0yQ.mjs';
+import { l as logger, p as projectPath, d as backoff, e as delay, R as RawJSONLinesSchema, c as configuration, f as readDaemonState, g as clearDaemonState, b as packageJson, r as readSettings, h as readCredentials, u as updateSettings, w as writeCredentials, i as unrealMcpPythonDir, j as acquireDaemonLock, k as writeDaemonState, m as ApiMachineClient, n as releaseDaemonLock, s as sendUnrealMcpTcpCommand, A as ApiClient, o as clearCredentials, q as clearMachineId, t as installUnrealMcpPluginToEngine, v as buildAndInstallUnrealMcpPlugin, x as getLatestDaemonLog, y as normalizeServerUrlForNode } from './types-DdJKBH6T.mjs';
 import { spawn, execFileSync, execSync } from 'node:child_process';
 import path, { resolve, join, dirname } from 'node:path';
 import { createInterface } from 'node:readline';
 import * as fs from 'node:fs';
 import fs__default, { existsSync, readFileSync, mkdirSync, readdirSync, accessSync, constants, statSync, createReadStream, writeFileSync, unlinkSync } from 'node:fs';
 import process$1 from 'node:process';
-import fs$1, { readFile, access as access$1, mkdir, readdir, stat, rename, open as open$1 } from 'node:fs/promises';
+import fs$1, { readFile, access as access$1, mkdir, readdir, stat, writeFile, rename, open as open$1 } from 'node:fs/promises';
 import fs$2, { watch, access } from 'fs/promises';
 import { useStdout, useInput, Box, Text, render } from 'ink';
 import React, { useState, useRef, useEffect, useCallback } from 'react';
@@ -35,6 +35,7 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import 'tweetnacl';
 import { createServer as createServer$1 } from 'http';
 import { promisify } from 'util';
+import { deflateSync } from 'node:zlib';
 
 class Session {
   path;
@@ -4651,6 +4652,10 @@ async function stopDaemonSession(sessionId) {
   const result = await daemonPost("/stop-session", { sessionId });
   return result.success || false;
 }
+async function spawnDaemonSession(directory, sessionId, agent) {
+  const result = await daemonPost("/spawn-session", { directory, sessionId, agent });
+  return result;
+}
 async function stopDaemonHttp() {
   await daemonPost("/stop");
 }
@@ -5331,7 +5336,8 @@ function startDaemonControlServer({
       schema: {
         body: z.object({
           directory: z.string(),
-          sessionId: z.string().optional()
+          sessionId: z.string().optional(),
+          agent: z.enum(["codex", "claude", "gemini"]).optional()
         }),
         response: {
           200: z.object({
@@ -5352,9 +5358,9 @@ function startDaemonControlServer({
         }
       }
     }, async (request, reply) => {
-      const { directory, sessionId } = request.body;
-      logger.debug(`[CONTROL SERVER] Spawn session request: dir=${directory}, sessionId=${sessionId || "new"}`);
-      const result = await spawnSession({ directory, sessionId });
+      const { directory, sessionId, agent } = request.body;
+      logger.debug(`[CONTROL SERVER] Spawn session request: dir=${directory}, sessionId=${sessionId || "new"}, agent=${agent || "default"}`);
+      const result = await spawnSession({ directory, sessionId, agent });
       switch (result.type) {
         case "success":
           if (!result.sessionId) {
@@ -6307,14 +6313,42 @@ Log: ${logPath || `not found (check ${configuration.logsDir})`}` + formatLogExce
       httpPort: controlPort,
       startedAt: Date.now()
     };
+    let hydratedMetadata = { ...initialMachineMetadata };
+    let hydratedSeq = 0;
+    try {
+      const endpoint = configuration.serverUrl.replace(/\/+$/, "");
+      const res = await fetch(`${endpoint}/v1/machines/${encodeURIComponent(machineId)}`, {
+        method: "GET",
+        headers: {
+          Authorization: `Machine ${credentials.machineToken}`
+        },
+        signal: AbortSignal.timeout(1e4)
+      });
+      if (res.ok) {
+        const data = await res.json().catch(() => null);
+        const existingMachine = data?.machine && typeof data.machine === "object" ? data.machine : null;
+        const existingMetadata = existingMachine?.metadata && typeof existingMachine.metadata === "object" ? existingMachine.metadata : null;
+        if (existingMetadata) {
+          hydratedMetadata = { ...existingMetadata, ...initialMachineMetadata };
+          hydratedSeq = Number(existingMachine?.seq || 0);
+        }
+      } else if (res.status !== 404) {
+        const detail = await res.text().catch(() => "");
+        logger.debug(
+          `[DAEMON RUN] Failed to hydrate machine metadata (status=${res.status}): ${detail.slice(0, 800)}`
+        );
+      }
+    } catch (err) {
+      logger.debug("[DAEMON RUN] Failed to hydrate machine metadata (best-effort):", err);
+    }
     const machine = {
       id: machineId,
-      seq: 0,
+      seq: hydratedSeq,
       active: false,
       activeAt: null,
       createdAt: null,
       updatedAt: null,
-      metadata: { ...initialMachineMetadata },
+      metadata: hydratedMetadata,
       daemonState: initialDaemonState
     };
     machineRef = machine;
@@ -7185,10 +7219,37 @@ async function runCmdAndCapture(args) {
 function serverBaseUrl() {
   return (configuration.serverUrl || "").replace(/\/+$/, "");
 }
+function readHttpTimeoutMs(envKey, fallbackMs) {
+  const raw = String(process.env[envKey] ?? "").trim();
+  const parsed = Number(raw);
+  if (Number.isFinite(parsed) && parsed > 0) return Math.max(250, parsed);
+  return fallbackMs;
+}
+function isAbortError(err) {
+  if (!err) return false;
+  if (typeof err === "object" && err.name === "AbortError") return true;
+  const msg = err instanceof Error ? err.message : String(err);
+  return /aborted|aborterror/i.test(msg);
+}
+async function fetchWithTimeout(url, init, timeoutMs, label) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } catch (err) {
+    if (isAbortError(err)) {
+      throw new Error(`Request timed out after ${timeoutMs}ms: ${label}`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
 async function uploadScreenshotViewsForSession(args) {
   const baseUrl = serverBaseUrl();
   if (!baseUrl) throw new Error("Missing configuration.serverUrl");
   const endpoint = `${baseUrl}/v1/sessions/${encodeURIComponent(args.sessionId)}/screenshots`;
+  const timeoutMs = readHttpTimeoutMs("FLOCKBAY_MCP_SCREENSHOT_UPLOAD_TIMEOUT_MS", 18e4);
   const form = new FormData();
   for (const v of args.views) {
     const buf = await readFile(v.path);
@@ -7201,15 +7262,20 @@ async function uploadScreenshotViewsForSession(args) {
     const blob = new Blob([buf], { type: contentType });
     form.append(`file:${v.id}`, blob, filename);
   }
-  const res = await fetch(endpoint, {
-    method: "POST",
-    headers: {
-      // This tool runs inside the CLI/daemon context, so we authenticate as the machine.
-      // The backend accepts `Machine <token>` for machine-scoped auth.
-      Authorization: `Machine ${args.token}`
+  const res = await fetchWithTimeout(
+    endpoint,
+    {
+      method: "POST",
+      headers: {
+        // This tool runs inside the CLI/daemon context, so we authenticate as the machine.
+        // The backend accepts `Machine <token>` for machine-scoped auth.
+        Authorization: `Machine ${args.token}`
+      },
+      body: form
     },
-    body: form
-  });
+    timeoutMs,
+    `POST ${endpoint}`
+  );
   if (!res.ok) {
     const text = await res.text().catch(() => "");
     throw new Error(`Screenshot upload failed (${res.status}): ${text || res.statusText}`);
@@ -7333,14 +7399,21 @@ async function startFlockbayServer(client, options) {
     logger.debug("[flockbayMCP] Failed to register elicitation RPC handler", err);
   }
   const postJson = async (pathname, body) => {
-    const res = await fetch(`${configuration.serverUrl.replace(/\/+$/, "")}${pathname}`, {
-      method: "POST",
-      headers: {
-        Authorization: `Machine ${client.getAuthToken()}`,
-        "Content-Type": "application/json"
+    const timeoutMs = readHttpTimeoutMs("FLOCKBAY_MCP_HTTP_TIMEOUT_MS", 6e4);
+    const url = `${configuration.serverUrl.replace(/\/+$/, "")}${pathname}`;
+    const res = await fetchWithTimeout(
+      url,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Machine ${client.getAuthToken()}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body ?? {})
       },
-      body: JSON.stringify(body ?? {})
-    });
+      timeoutMs,
+      `POST ${url}`
+    );
     const data = await res.json().catch(() => null);
     if (!res.ok) {
       const msg = typeof data?.error === "string" ? data.error : `Request failed (${res.status})`;
@@ -7774,20 +7847,200 @@ ${String(st.stdout || "").trim()}`
       isError
     };
   };
-  const runWithMcpToolCard = async (toolName, input, fn) => {
-    const callId = emitFlockbayMcpToolCall(toolName, input);
-    try {
-      const result = await fn();
-      emitFlockbayMcpToolResult(callId, result, Boolean(result?.isError));
-      return result;
-    } catch (err) {
-      const fallback = textToolResult(
-        `Tool "${toolName}" failed: ${err instanceof Error ? err.message : String(err)}`,
-        true
-      );
-      emitFlockbayMcpToolResult(callId, fallback, true);
-      return fallback;
+  let mcpToolRunChain = Promise.resolve();
+  const runMcpToolSerialized = async (fn) => {
+    const res = mcpToolRunChain.then(fn, fn);
+    mcpToolRunChain = res.then(() => void 0, () => void 0);
+    return await res;
+  };
+  const toolResultsArtifactsRoot = () => {
+    const sessionDir = readSessionWorkingDirectory();
+    return path.join(sessionDir, ".flockbay", "artifacts", "tool-results");
+  };
+  const safePathSegment = (raw) => String(raw || "").trim().replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+/, "").replace(/_+$/, "") || "unknown";
+  const coerceTextBlocks = (content) => {
+    if (!Array.isArray(content)) return [];
+    const out = [];
+    for (const block of content) {
+      if (!block || typeof block !== "object") continue;
+      if (block.type !== "text") continue;
+      const t = block.text;
+      if (typeof t === "string" && t.trim()) out.push(t.trim());
+    }
+    return out;
+  };
+  const writeToolResultArtifact = async (args) => {
+    const root = toolResultsArtifactsRoot();
+    const toolDir = path.join(root, safePathSegment(args.toolName));
+    await mkdir(toolDir, { recursive: true });
+    const filePath = path.join(toolDir, `${safePathSegment(args.toolResultId)}.json`);
+    const payload = {
+      kind: "mcp_tool_result",
+      toolName: args.toolName,
+      toolResultId: args.toolResultId,
+      isError: args.isError,
+      createdAtMs: Date.now(),
+      input: args.input ?? null,
+      output: args.output ?? null
+    };
+    await writeFile(filePath, JSON.stringify(payload, null, 2), "utf8");
+    return { id: args.toolResultId, path: filePath };
+  };
+  const buildModelMinimalToolResult = (args) => {
+    const headLines = [];
+    if (args.isError) headLines.push(`Tool failed: ${args.toolName}`);
+    else headLines.push(`Tool completed: ${args.toolName}`);
+    const texts = coerceTextBlocks(args.fullResult?.content);
+    const first = texts[0];
+    if (first && !/^\s*[{[]/.test(first)) headLines.push(first);
+    headLines.push(`Evidence: toolResultId=${args.artifact.id}`);
+    headLines.push(`Tip: use tool_result_query/tool_result_read for details (avoid re-reading full tool JSON unless necessary).`);
+    const modelContent = [{ type: "text", text: headLines.join("\n") }];
+    if (args.passthroughContent && Array.isArray(args.fullResult?.content)) {
+      for (const block of args.fullResult.content) {
+        if (!block || typeof block !== "object") continue;
+        if (block.type === "image") modelContent.push(block);
+      }
+    }
+    const views = Array.isArray(args.fullResult?.views) ? args.fullResult.views : null;
+    const safeViews = views && views.map((v) => {
+      if (!v || typeof v !== "object") return v;
+      const { base64: _base64, data: _data, ...rest } = v;
+      return rest;
+    });
+    return {
+      content: modelContent,
+      ...safeViews ? { views: safeViews } : {},
+      isError: args.isError,
+      toolResultId: args.artifact.id
+    };
+  };
+  const resolveToolResultArtifactPath = async (args) => {
+    const root = toolResultsArtifactsRoot();
+    const resolvedRoot = path.resolve(root);
+    const toolResultId = String(args.toolResultId || "").trim();
+    if (!toolResultId) return { ok: false, error: "Missing toolResultId." };
+    const rawPath = String(args.artifactPath || "").trim();
+    const toolName = String(args.toolName || "").trim();
+    const safeId = safePathSegment(toolResultId);
+    let filePath = "";
+    if (rawPath) {
+      filePath = rawPath;
+    } else if (toolName) {
+      filePath = path.join(root, safePathSegment(toolName), `${safeId}.json`);
+    } else {
+      if (!existsSync(root)) return { ok: false, error: `Tool results root not found: ${root}` };
+      const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+      const matches = [];
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const candidate = path.join(root, entry.name, `${safeId}.json`);
+        if (existsSync(candidate)) matches.push(candidate);
+      }
+      if (matches.length === 0) return { ok: false, error: `tool result not found: ${toolResultId}` };
+      if (matches.length > 1) {
+        return {
+          ok: false,
+          error: `tool result id is ambiguous (found in multiple tool folders). Provide toolName to disambiguate. toolResultId=${toolResultId}`
+        };
+      }
+      filePath = matches[0];
+    }
+    const resolvedFile = path.resolve(filePath);
+    if (!resolvedFile.startsWith(resolvedRoot + path.sep) && resolvedFile !== resolvedRoot) {
+      return { ok: false, error: `Refusing to read outside tool-results root.` };
+    }
+    if (!existsSync(resolvedFile)) return { ok: false, error: `tool result artifact not found` };
+    return { ok: true, path: resolvedFile };
+  };
+  const normalizeQueryPath = (raw) => {
+    const s = String(raw || "").trim();
+    if (!s) return "";
+    if (s.startsWith("/")) return s;
+    const parts = s.split(".").map((p) => p.trim()).filter(Boolean).map((p) => p.replace(/~/g, "~0").replace(/\//g, "~1"));
+    return `/${parts.join("/")}`;
+  };
+  const getValueAtJsonPointer = (root, pointerRaw) => {
+    const pointer = normalizeQueryPath(pointerRaw);
+    if (!pointer) return { ok: false, error: "Empty path." };
+    if (pointer === "/" || pointer === "") return { ok: true, value: root };
+    if (!pointer.startsWith("/")) return { ok: false, error: 'Invalid JSON pointer (must start with "/").' };
+    const decode = (seg) => seg.replace(/~1/g, "/").replace(/~0/g, "~");
+    const segments = pointer.split("/").slice(1).map((seg) => decode(seg));
+    let cur = root;
+    for (const seg of segments) {
+      if (cur == null) return { ok: false, error: `Missing path segment: ${seg}` };
+      if (Array.isArray(cur)) {
+        if (!/^\d+$/.test(seg)) return { ok: false, error: `Expected array index but got "${seg}"` };
+        const idx = Number(seg);
+        if (!Number.isFinite(idx) || idx < 0 || idx >= cur.length) return { ok: false, error: `Array index out of range: ${seg}` };
+        cur = cur[idx];
+        continue;
+      }
+      if (typeof cur !== "object") return { ok: false, error: `Cannot descend into non-object at "${seg}"` };
+      if (!(seg in cur)) return { ok: false, error: `Missing key: ${seg}` };
+      cur = cur[seg];
     }
+    return { ok: true, value: cur };
+  };
+  const runWithMcpToolCard = async (toolName, input, fn, options2) => {
+    return await runMcpToolSerialized(async () => {
+      const uiCallId = emitFlockbayMcpToolCall(toolName, input);
+      const toolResultId = uiCallId || randomUUID();
+      try {
+        const fullResult = await fn();
+        const isError = Boolean(fullResult?.isError);
+        const artifact = await writeToolResultArtifact({
+          toolName,
+          toolResultId,
+          input,
+          output: fullResult,
+          isError
+        });
+        const uiPayload = fullResult && typeof fullResult === "object" && !Array.isArray(fullResult) ? { ...fullResult, toolResultId: artifact.id, artifactPath: artifact.path } : fullResult;
+        emitFlockbayMcpToolResult(uiCallId, uiPayload, isError);
+        if (options2?.modelReturn === "full") {
+          if (fullResult && typeof fullResult === "object" && !Array.isArray(fullResult)) {
+            return { ...fullResult, toolResultId: artifact.id, isError };
+          }
+          return fullResult;
+        }
+        return buildModelMinimalToolResult({
+          toolName,
+          artifact,
+          fullResult,
+          isError,
+          passthroughContent: Boolean(options2?.passthroughImagesToModel)
+        });
+      } catch (err) {
+        const fullResult = textToolResult(
+          `Tool "${toolName}" failed: ${err instanceof Error ? err.message : String(err)}`,
+          true
+        );
+        const artifact = await writeToolResultArtifact({
+          toolName,
+          toolResultId,
+          input,
+          output: fullResult,
+          isError: true
+        });
+        const uiPayload = fullResult && typeof fullResult === "object" && !Array.isArray(fullResult) ? { ...fullResult, toolResultId: artifact.id, artifactPath: artifact.path } : fullResult;
+        emitFlockbayMcpToolResult(uiCallId, uiPayload, true);
+        if (options2?.modelReturn === "full") {
+          if (fullResult && typeof fullResult === "object" && !Array.isArray(fullResult)) {
+            return { ...fullResult, toolResultId: artifact.id, isError: true };
+          }
+          return fullResult;
+        }
+        return buildModelMinimalToolResult({
+          toolName,
+          artifact,
+          fullResult,
+          isError: true,
+          passthroughContent: Boolean(options2?.passthroughImagesToModel)
+        });
+      }
+    });
   };
   mcp.registerTool(
     "ask_user_question",
@@ -7811,27 +8064,15 @@ ${String(st.stdout || "").trim()}`
         )
       }
     },
-    async (args) => {
-      const callId = emitFlockbayMcpToolCall("ask_user_question", args);
-      if (!callId) {
-        return textToolResult("AskUserQuestion is unavailable (no UI client attached).", true);
-      }
-      try {
-        const result = textToolResult(
-          [
-            "Questions were shown to the user.",
-            "Stop here and wait for the user to send a new message with the answers when ready."
-          ].join("\n"),
-          false
-        );
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`AskUserQuestion failed: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async (args) => runWithMcpToolCard("ask_user_question", args, async () => {
+      return textToolResult(
+        [
+          "Questions were shown to the user.",
+          "Stop here and wait for the user to send a new message with the answers when ready."
+        ].join("\n"),
+        false
+      );
+    })
   );
   mcp.registerTool("change_title", {
     description: "Change the title of the current chat session",
@@ -7870,28 +8111,19 @@ ${String(st.stdout || "").trim()}`
       description: "Fetch the current coordination ledger snapshot (work items + planned/active/done intent) for this project.",
       inputSchema: {}
     },
-    async () => {
-      const callId = emitFlockbayMcpToolCall("coordination_ledger_snapshot", {});
-      try {
-        const { projectId } = readCoordinationIds();
-        const data = await postJson("/v1/coordination/work-items/list", { projectId });
-        if (typeof client?.markCoordinationLedgerRead === "function") {
-          try {
-            client.markCoordinationLedgerRead();
-          } catch (error) {
-            console.error("[flockbayMCP] markCoordinationLedgerRead failed:", error);
-            logger.debug("[flockbayMCP] markCoordinationLedgerRead failed:", error);
-          }
+    async () => runWithMcpToolCard("coordination_ledger_snapshot", {}, async () => {
+      const { projectId } = readCoordinationIds();
+      const data = await postJson("/v1/coordination/work-items/list", { projectId });
+      if (typeof client?.markCoordinationLedgerRead === "function") {
+        try {
+          client.markCoordinationLedgerRead();
+        } catch (error) {
+          console.error("[flockbayMCP] markCoordinationLedgerRead failed:", error);
+          logger.debug("[flockbayMCP] markCoordinationLedgerRead failed:", error);
         }
-        const result = textToolResult(JSON.stringify({ projectId, workItems: data?.workItems ?? [] }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to fetch ledger snapshot: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
       }
-    }
+      return textToolResult(JSON.stringify({ projectId, workItems: data?.workItems ?? [] }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "ledger_read",
@@ -7900,28 +8132,19 @@ ${String(st.stdout || "").trim()}`
       description: "Alias for coordination_ledger_snapshot: fetch the current shared coordination ledger snapshot for this project.",
       inputSchema: {}
     },
-    async () => {
-      const callId = emitFlockbayMcpToolCall("ledger_read", {});
-      try {
-        const { projectId } = readCoordinationIds();
-        const data = await postJson("/v1/coordination/work-items/list", { projectId });
-        if (typeof client?.markCoordinationLedgerRead === "function") {
-          try {
-            client.markCoordinationLedgerRead();
-          } catch (error) {
-            console.error("[flockbayMCP] markCoordinationLedgerRead failed:", error);
-            logger.debug("[flockbayMCP] markCoordinationLedgerRead failed:", error);
-          }
+    async () => runWithMcpToolCard("ledger_read", {}, async () => {
+      const { projectId } = readCoordinationIds();
+      const data = await postJson("/v1/coordination/work-items/list", { projectId });
+      if (typeof client?.markCoordinationLedgerRead === "function") {
+        try {
+          client.markCoordinationLedgerRead();
+        } catch (error) {
+          console.error("[flockbayMCP] markCoordinationLedgerRead failed:", error);
+          logger.debug("[flockbayMCP] markCoordinationLedgerRead failed:", error);
         }
-        const result = textToolResult(JSON.stringify({ projectId, workItems: data?.workItems ?? [] }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to read ledger: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
       }
-    }
+      return textToolResult(JSON.stringify({ projectId, workItems: data?.workItems ?? [] }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "docs_index_read",
@@ -7930,58 +8153,49 @@ ${String(st.stdout || "").trim()}`
       description: "Read the required game Documentation index (index.md) and a compact tree summary. Marks this session as having read the docs index.",
       inputSchema: {}
     },
-    async () => {
-      const callId = emitFlockbayMcpToolCall("docs_index_read", {});
-      try {
-        const { projectId } = readCoordinationIds();
-        const sessionId = String(client?.sessionId || "").trim();
-        const meta = client?.metadata;
-        const machineId = String(meta?.machineId || "").trim() || null;
-        const index = await postJson("/v1/workspace/projects/docs/index", {
-          workspaceProjectId: projectId
-        });
-        const tree = await postJson("/v1/workspace/projects/docs/tree", {
-          workspaceProjectId: projectId
-        });
-        if (typeof client?.markDocsIndexRead === "function") {
-          try {
-            client.markDocsIndexRead();
-          } catch (error) {
-            console.error("[flockbayMCP] markDocsIndexRead failed:", error);
-            logger.debug("[flockbayMCP] markDocsIndexRead failed:", error);
-          }
-        }
-        const nodes = Array.isArray(tree?.nodes) ? tree.nodes : [];
-        const compact = nodes.filter((n) => n && (n.kind === "folder" || n.kind === "document")).map((n) => ({
-          id: n.id,
-          kind: n.kind,
-          parentId: n.parentId ?? null,
-          name: n.name,
-          title: n.metadata && n.metadata.title || null,
-          isIndex: Boolean(n.isIndex)
-        }));
-        const result = textToolResult(
-          JSON.stringify(
-            {
-              workspaceProjectId: projectId,
-              sessionId,
-              machineId,
-              index: index?.doc ?? null,
-              tree: compact
-            },
-            null,
-            2
-          ),
-          false
-        );
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to read docs index: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async () => runWithMcpToolCard("docs_index_read", {}, async () => {
+      const { projectId } = readCoordinationIds();
+      const sessionId = String(client?.sessionId || "").trim();
+      const meta = client?.metadata;
+      const machineId = String(meta?.machineId || "").trim() || null;
+      const index = await postJson("/v1/workspace/projects/docs/index", {
+        workspaceProjectId: projectId
+      });
+      const tree = await postJson("/v1/workspace/projects/docs/tree", {
+        workspaceProjectId: projectId
+      });
+      if (typeof client?.markDocsIndexRead === "function") {
+        try {
+          client.markDocsIndexRead();
+        } catch (error) {
+          console.error("[flockbayMCP] markDocsIndexRead failed:", error);
+          logger.debug("[flockbayMCP] markDocsIndexRead failed:", error);
+        }
+      }
+      const nodes = Array.isArray(tree?.nodes) ? tree.nodes : [];
+      const compact = nodes.filter((n) => n && (n.kind === "folder" || n.kind === "document")).map((n) => ({
+        id: n.id,
+        kind: n.kind,
+        parentId: n.parentId ?? null,
+        name: n.name,
+        title: n.metadata && n.metadata.title || null,
+        isIndex: Boolean(n.isIndex)
+      }));
+      return textToolResult(
+        JSON.stringify(
+          {
+            workspaceProjectId: projectId,
+            sessionId,
+            machineId,
+            index: index?.doc ?? null,
+            tree: compact
+          },
+          null,
+          2
+        ),
+        false
+      );
+    })
   );
   mcp.registerTool(
     "docs_tree",
@@ -7990,22 +8204,16 @@ ${String(st.stdout || "").trim()}`
       description: "Fetch the Documentation Library tree (folders + docs metadata; no bodies).",
       inputSchema: {}
     },
-    async () => {
-      const callId = emitFlockbayMcpToolCall("docs_tree", {});
-      try {
-        const { projectId } = readCoordinationIds();
-        const tree = await postJson("/v1/workspace/projects/docs/tree", {
-          workspaceProjectId: projectId
-        });
-        const result = textToolResult(JSON.stringify({ workspaceProjectId: projectId, library: tree?.library ?? null, nodes: tree?.nodes ?? [] }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to fetch docs tree: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async () => runWithMcpToolCard("docs_tree", {}, async () => {
+      const { projectId } = readCoordinationIds();
+      const tree = await postJson("/v1/workspace/projects/docs/tree", {
+        workspaceProjectId: projectId
+      });
+      return textToolResult(
+        JSON.stringify({ workspaceProjectId: projectId, library: tree?.library ?? null, nodes: tree?.nodes ?? [] }, null, 2),
+        false
+      );
+    })
   );
   mcp.registerTool(
     "docs_get",
@@ -8016,22 +8224,13 @@ ${String(st.stdout || "").trim()}`
         nodeId: z.string().describe("Document node id.")
       }
     },
-    async (args) => {
-      const callId = emitFlockbayMcpToolCall("docs_get", args);
-      try {
-        const { projectId } = readCoordinationIds();
-        const nodeId = String(args?.nodeId || "").trim();
-        if (!nodeId) return textToolResult("Missing nodeId", true);
-        const node = await postJson("/v1/workspace/projects/docs/get", { workspaceProjectId: projectId, nodeId });
-        const result = textToolResult(JSON.stringify({ workspaceProjectId: projectId, node: node?.node ?? null }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to fetch doc: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async (args) => runWithMcpToolCard("docs_get", args, async () => {
+      const { projectId } = readCoordinationIds();
+      const nodeId = String(args?.nodeId || "").trim();
+      if (!nodeId) return textToolResult("Missing nodeId", true);
+      const node = await postJson("/v1/workspace/projects/docs/get", { workspaceProjectId: projectId, nodeId });
+      return textToolResult(JSON.stringify({ workspaceProjectId: projectId, node: node?.node ?? null }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "docs_search",
@@ -8043,26 +8242,17 @@ ${String(st.stdout || "").trim()}`
         limit: z.number().int().positive().optional().describe("Max results (default 50).")
       }
     },
-    async (args) => {
-      const callId = emitFlockbayMcpToolCall("docs_search", args);
-      try {
-        const { projectId } = readCoordinationIds();
-        const q = String(args?.q || "").trim();
-        const limit = args?.limit;
-        const res = await postJson("/v1/workspace/projects/docs/search", {
-          workspaceProjectId: projectId,
-          q,
-          limit
-        });
-        const result = textToolResult(JSON.stringify({ workspaceProjectId: projectId, results: res?.results ?? [] }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to search docs: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async (args) => runWithMcpToolCard("docs_search", args, async () => {
+      const { projectId } = readCoordinationIds();
+      const q = String(args?.q || "").trim();
+      const limit = args?.limit;
+      const res = await postJson("/v1/workspace/projects/docs/search", {
+        workspaceProjectId: projectId,
+        q,
+        limit
+      });
+      return textToolResult(JSON.stringify({ workspaceProjectId: projectId, results: res?.results ?? [] }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "docs_create_folder",
@@ -8074,26 +8264,17 @@ ${String(st.stdout || "").trim()}`
         parentId: z.string().optional().describe("Parent folder node id (defaults to root).")
       }
     },
-    async (args) => {
-      const callId = emitFlockbayMcpToolCall("docs_create_folder", args);
-      try {
-        const { projectId } = readCoordinationIds();
-        const name = String(args?.name || "").trim();
-        const parentId = args?.parentId ? String(args.parentId).trim() : void 0;
-        const res = await postJson("/v1/workspace/projects/docs/create-folder", {
-          workspaceProjectId: projectId,
-          name,
-          parentId
-        });
-        const result = textToolResult(JSON.stringify({ workspaceProjectId: projectId, node: res?.node ?? null }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to create folder: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async (args) => runWithMcpToolCard("docs_create_folder", args, async () => {
+      const { projectId } = readCoordinationIds();
+      const name = String(args?.name || "").trim();
+      const parentId = args?.parentId ? String(args.parentId).trim() : void 0;
+      const res = await postJson("/v1/workspace/projects/docs/create-folder", {
+        workspaceProjectId: projectId,
+        name,
+        parentId
+      });
+      return textToolResult(JSON.stringify({ workspaceProjectId: projectId, node: res?.node ?? null }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "docs_create_doc",
@@ -8107,30 +8288,21 @@ ${String(st.stdout || "").trim()}`
         metadata: z.record(z.any()).optional().describe("Metadata object (JSON).")
       }
     },
-    async (args) => {
-      const callId = emitFlockbayMcpToolCall("docs_create_doc", args);
-      try {
-        const { projectId } = readCoordinationIds();
-        const name = String(args?.name || "").trim();
-        const parentId = args?.parentId ? String(args.parentId).trim() : void 0;
-        const bodyMarkdown = args?.bodyMarkdown ?? "";
-        const metadata = args?.metadata ?? {};
-        const res = await postJson("/v1/workspace/projects/docs/create-doc", {
-          workspaceProjectId: projectId,
-          name,
-          parentId,
-          bodyMarkdown,
-          metadata
-        });
-        const result = textToolResult(JSON.stringify({ workspaceProjectId: projectId, node: res?.node ?? null }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to create doc: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async (args) => runWithMcpToolCard("docs_create_doc", args, async () => {
+      const { projectId } = readCoordinationIds();
+      const name = String(args?.name || "").trim();
+      const parentId = args?.parentId ? String(args.parentId).trim() : void 0;
+      const bodyMarkdown = args?.bodyMarkdown ?? "";
+      const metadata = args?.metadata ?? {};
+      const res = await postJson("/v1/workspace/projects/docs/create-doc", {
+        workspaceProjectId: projectId,
+        name,
+        parentId,
+        bodyMarkdown,
+        metadata
+      });
+      return textToolResult(JSON.stringify({ workspaceProjectId: projectId, node: res?.node ?? null }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "docs_claim",
@@ -8142,32 +8314,23 @@ ${String(st.stdout || "").trim()}`
         leaseMs: z.number().int().positive().optional().describe("Lease TTL (ms).")
       }
     },
-    async (args) => {
-      const callId = emitFlockbayMcpToolCall("docs_claim", args);
-      try {
-        const { projectId, workItemId } = readCoordinationIds();
-        const sessionId = String(client?.sessionId || "").trim();
-        const meta = client?.metadata;
-        const machineId = String(meta?.machineId || "").trim() || null;
-        const nodeId = String(args?.nodeId || "").trim();
-        const leaseMs = args?.leaseMs;
-        const res = await postJson("/v1/workspace/projects/docs/leases/claim", {
-          workspaceProjectId: projectId,
-          nodeId,
-          workItemId,
-          sessionId,
-          machineId,
-          leaseMs
-        });
-        const result = textToolResult(JSON.stringify({ workspaceProjectId: projectId, ...res }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to claim doc: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async (args) => runWithMcpToolCard("docs_claim", args, async () => {
+      const { projectId, workItemId } = readCoordinationIds();
+      const sessionId = String(client?.sessionId || "").trim();
+      const meta = client?.metadata;
+      const machineId = String(meta?.machineId || "").trim() || null;
+      const nodeId = String(args?.nodeId || "").trim();
+      const leaseMs = args?.leaseMs;
+      const res = await postJson("/v1/workspace/projects/docs/leases/claim", {
+        workspaceProjectId: projectId,
+        nodeId,
+        workItemId,
+        sessionId,
+        machineId,
+        leaseMs
+      });
+      return textToolResult(JSON.stringify({ workspaceProjectId: projectId, ...res }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "docs_release",
@@ -8178,27 +8341,18 @@ ${String(st.stdout || "").trim()}`
         nodeId: z.string().describe("Document node id.")
       }
     },
-    async (args) => {
-      const callId = emitFlockbayMcpToolCall("docs_release", args);
-      try {
-        const { projectId, workItemId } = readCoordinationIds();
-        const sessionId = String(client?.sessionId || "").trim();
-        const nodeId = String(args?.nodeId || "").trim();
-        const res = await postJson("/v1/workspace/projects/docs/leases/release", {
-          workspaceProjectId: projectId,
-          nodeId,
-          workItemId,
-          sessionId
-        });
-        const result = textToolResult(JSON.stringify({ workspaceProjectId: projectId, ...res }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to release doc: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async (args) => runWithMcpToolCard("docs_release", args, async () => {
+      const { projectId, workItemId } = readCoordinationIds();
+      const sessionId = String(client?.sessionId || "").trim();
+      const nodeId = String(args?.nodeId || "").trim();
+      const res = await postJson("/v1/workspace/projects/docs/leases/release", {
+        workspaceProjectId: projectId,
+        nodeId,
+        workItemId,
+        sessionId
+      });
+      return textToolResult(JSON.stringify({ workspaceProjectId: projectId, ...res }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "docs_update",
@@ -8213,56 +8367,47 @@ ${String(st.stdout || "").trim()}`
         expectedBodyVersion: z.number().int().nonnegative().optional().describe("Optional optimistic concurrency check.")
       }
     },
-    async (args) => {
-      const callId = emitFlockbayMcpToolCall("docs_update", args);
+    async (args) => runWithMcpToolCard("docs_update", args, async () => {
+      const { projectId, workItemId } = readCoordinationIds();
+      const sessionId = String(client?.sessionId || "").trim();
+      const nodeId = String(args?.nodeId || "").trim();
+      const name = args?.name;
+      const bodyMarkdown = args?.bodyMarkdown;
+      const metadata = args?.metadata;
+      const expectedBodyVersion = args?.expectedBodyVersion;
+      const attemptUpdate = async () => {
+        return await postJson("/v1/workspace/projects/docs/update-doc", {
+          workspaceProjectId: projectId,
+          nodeId,
+          workItemId,
+          sessionId,
+          name,
+          bodyMarkdown,
+          metadata,
+          expectedBodyVersion
+        });
+      };
+      let res;
       try {
-        const { projectId, workItemId } = readCoordinationIds();
-        const sessionId = String(client?.sessionId || "").trim();
-        const nodeId = String(args?.nodeId || "").trim();
-        const name = args?.name;
-        const bodyMarkdown = args?.bodyMarkdown;
-        const metadata = args?.metadata;
-        const expectedBodyVersion = args?.expectedBodyVersion;
-        const attemptUpdate = async () => {
-          return await postJson("/v1/workspace/projects/docs/update-doc", {
+        res = await attemptUpdate();
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg === "lease_required") {
+          await postJson("/v1/workspace/projects/docs/leases/claim", {
             workspaceProjectId: projectId,
             nodeId,
             workItemId,
             sessionId,
-            name,
-            bodyMarkdown,
-            metadata,
-            expectedBodyVersion
+            machineId: String(client?.metadata?.machineId || "").trim() || null,
+            leaseMs: 2 * 6e4
           });
-        };
-        let res;
-        try {
           res = await attemptUpdate();
-        } catch (e) {
-          const msg = e instanceof Error ? e.message : String(e);
-          if (msg === "lease_required") {
-            await postJson("/v1/workspace/projects/docs/leases/claim", {
-              workspaceProjectId: projectId,
-              nodeId,
-              workItemId,
-              sessionId,
-              machineId: String(client?.metadata?.machineId || "").trim() || null,
-              leaseMs: 2 * 6e4
-            });
-            res = await attemptUpdate();
-          } else {
-            throw e;
-          }
+        } else {
+          throw e;
         }
-        const result = textToolResult(JSON.stringify({ workspaceProjectId: projectId, ...res }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to update doc: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
       }
-    }
+      return textToolResult(JSON.stringify({ workspaceProjectId: projectId, ...res }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "docs_delete",
@@ -8273,27 +8418,18 @@ ${String(st.stdout || "").trim()}`
         nodeId: z.string().describe("Node id (folder or document).")
       }
     },
-    async (args) => {
-      const callId = emitFlockbayMcpToolCall("docs_delete", args);
-      try {
-        const { projectId, workItemId } = readCoordinationIds();
-        const sessionId = String(client?.sessionId || "").trim();
-        const nodeId = String(args?.nodeId || "").trim();
-        const res = await postJson("/v1/workspace/projects/docs/delete-node", {
-          workspaceProjectId: projectId,
-          nodeId,
-          workItemId,
-          sessionId
-        });
-        const result = textToolResult(JSON.stringify({ workspaceProjectId: projectId, ...res }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to delete node: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async (args) => runWithMcpToolCard("docs_delete", args, async () => {
+      const { projectId, workItemId } = readCoordinationIds();
+      const sessionId = String(client?.sessionId || "").trim();
+      const nodeId = String(args?.nodeId || "").trim();
+      const res = await postJson("/v1/workspace/projects/docs/delete-node", {
+        workspaceProjectId: projectId,
+        nodeId,
+        workItemId,
+        sessionId
+      });
+      return textToolResult(JSON.stringify({ workspaceProjectId: projectId, ...res }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "docs_import",
@@ -8309,21 +8445,12 @@ ${String(st.stdout || "").trim()}`
         )
       }
     },
-    async (args) => {
-      const callId = emitFlockbayMcpToolCall("docs_import", args);
-      try {
-        const { projectId } = readCoordinationIds();
-        const entries = Array.isArray(args?.entries) ? args.entries : [];
-        const res = await postJson("/v1/workspace/projects/docs/import", { workspaceProjectId: projectId, entries });
-        const result = textToolResult(JSON.stringify({ workspaceProjectId: projectId, ...res }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to import docs: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async (args) => runWithMcpToolCard("docs_import", args, async () => {
+      const { projectId } = readCoordinationIds();
+      const entries = Array.isArray(args?.entries) ? args.entries : [];
+      const res = await postJson("/v1/workspace/projects/docs/import", { workspaceProjectId: projectId, entries });
+      return textToolResult(JSON.stringify({ workspaceProjectId: projectId, ...res }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "evidence_list",
@@ -8337,10 +8464,11 @@ ${String(st.stdout || "").trim()}`
     async (args) => runWithMcpToolCard("evidence_list", args, async () => {
       const limit = Math.max(1, Math.min(200, Number(args?.limit || 50) || 50));
       const url = `${configuration.serverUrl.replace(/\/+$/, "")}/v1/sessions/${encodeURIComponent(client.sessionId)}/evidence-artifacts?limit=${limit}`;
-      const res = await fetch(url, {
+      const timeoutMs = readHttpTimeoutMs("FLOCKBAY_MCP_HTTP_TIMEOUT_MS", 6e4);
+      const res = await fetchWithTimeout(url, {
         method: "GET",
         headers: { Authorization: `Machine ${client.getAuthToken()}`, accept: "application/json" }
-      });
+      }, timeoutMs, `GET ${url}`);
       const data = await res.json().catch(() => null);
       if (!res.ok) {
         const msg = typeof data?.error === "string" ? data.error : `Request failed (${res.status})`;
@@ -8362,10 +8490,11 @@ ${String(st.stdout || "").trim()}`
       const id = String(args?.evidenceArtifactId || "").trim();
       if (!id) return textToolResult("missing-evidenceArtifactId", true);
       const url = `${configuration.serverUrl.replace(/\/+$/, "")}/v1/sessions/${encodeURIComponent(client.sessionId)}/evidence-artifacts/${encodeURIComponent(id)}`;
-      const res = await fetch(url, {
+      const timeoutMs = readHttpTimeoutMs("FLOCKBAY_MCP_HTTP_TIMEOUT_MS", 6e4);
+      const res = await fetchWithTimeout(url, {
         method: "GET",
         headers: { Authorization: `Machine ${client.getAuthToken()}`, accept: "application/json" }
-      });
+      }, timeoutMs, `GET ${url}`);
       const data = await res.json().catch(() => null);
       if (!res.ok) {
         const msg = typeof data?.error === "string" ? data.error : `Request failed (${res.status})`;
@@ -8374,6 +8503,72 @@ ${String(st.stdout || "").trim()}`
       return textToolResult(JSON.stringify(data, null, 2), false);
     })
   );
+  mcp.registerTool(
+    "tool_result_read",
+    {
+      title: "Tool Result Read",
+      description: "Read a previously-stored MCP tool result artifact produced by Flockbay MCP (full tool input/output JSON). Use this when you explicitly need details beyond the default minimal tool observation.",
+      inputSchema: {
+        toolName: z.string().optional().describe("Tool name (folder under .flockbay/artifacts/tool-results)."),
+        toolResultId: z.string().describe("toolResultId from a prior tool observation."),
+        artifactPath: z.string().optional().describe("Optional absolute artifact path (advanced).")
+      }
+    },
+    async (args) => runWithMcpToolCard("tool_result_read", args, async () => {
+      const toolName = typeof args?.toolName === "string" ? String(args.toolName).trim() : null;
+      const toolResultId = typeof args?.toolResultId === "string" ? String(args.toolResultId).trim() : "";
+      const artifactPath = typeof args?.artifactPath === "string" ? String(args.artifactPath).trim() : null;
+      const resolved = await resolveToolResultArtifactPath({ toolName, toolResultId, artifactPath });
+      if (!resolved.ok) return textToolResult(resolved.error, true);
+      const raw = await readFile(resolved.path, "utf8");
+      return {
+        content: [
+          { type: "text", text: raw }
+        ],
+        isError: false
+      };
+    }, { modelReturn: "full" })
+  );
+  mcp.registerTool(
+    "tool_result_query",
+    {
+      title: "Tool Result Query",
+      description: "Query one or more JSON paths from a stored tool result artifact (small slices). Prefer this over reading the full artifact to avoid re-injecting huge payloads into the model context.",
+      inputSchema: {
+        toolName: z.string().optional().describe("Tool name (folder under .flockbay/artifacts/tool-results)."),
+        toolResultId: z.string().describe("toolResultId from a prior tool observation."),
+        artifactPath: z.string().optional().describe("Optional absolute artifact path (advanced)."),
+        paths: z.array(z.string()).min(1).describe('JSON pointer paths ("/output/result/location") or dot-paths ("output.result.location").')
+      }
+    },
+    async (args) => runWithMcpToolCard("tool_result_query", args, async () => {
+      const toolName = typeof args?.toolName === "string" ? String(args.toolName).trim() : null;
+      const toolResultId = typeof args?.toolResultId === "string" ? String(args.toolResultId).trim() : "";
+      const artifactPath = typeof args?.artifactPath === "string" ? String(args.artifactPath).trim() : null;
+      const paths = Array.isArray(args?.paths) ? args.paths.map((p) => String(p || "").trim()).filter(Boolean) : [];
+      if (!toolResultId) return textToolResult("Missing toolResultId.", true);
+      if (paths.length === 0) return textToolResult("Missing paths[] (provide one or more JSON paths).", true);
+      const resolved = await resolveToolResultArtifactPath({ toolName, toolResultId, artifactPath });
+      if (!resolved.ok) return textToolResult(resolved.error, true);
+      let json;
+      try {
+        json = JSON.parse(await readFile(resolved.path, "utf8"));
+      } catch (err) {
+        return textToolResult(`Failed to parse tool result artifact JSON: ${err instanceof Error ? err.message : String(err)}`, true);
+      }
+      const out = {};
+      for (const p of paths) {
+        const res = getValueAtJsonPointer(json, p);
+        if (!res.ok) return textToolResult(`Invalid path "${p}": ${res.error}`, true);
+        out[p] = res.value;
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify({ toolResultId, values: out }, null, 2) }],
+        values: out,
+        isError: false
+      };
+    }, { modelReturn: "full" })
+  );
   mcp.registerTool(
     "coordination_update_intent",
     {
@@ -8389,31 +8584,22 @@ ${String(st.stdout || "").trim()}`
         leaseMs: z.number().int().positive().optional().describe("Soft lease TTL for this ledger entry (ms). UI-only staleness hint; default ~2h.")
       }
     },
-    async (args) => {
-      const callId = emitFlockbayMcpToolCall("coordination_update_intent", args);
-      try {
-        const { projectId, workItemId } = readCoordinationIds();
-        const body = {
-          projectId,
-          workItemId,
-          summary: args?.summary ?? void 0,
-          status: args?.status ?? void 0,
-          plannedFiles: args?.plannedFiles ?? void 0,
-          activeFiles: args?.activeFiles ?? void 0,
-          doneFiles: args?.doneFiles ?? void 0,
-          waitingOnFiles: args?.waitingOnFiles ?? void 0,
-          leaseMs: args?.leaseMs ?? void 0
-        };
-        const data = await postJson("/v1/coordination/work-items/update", body);
-        const result = textToolResult(JSON.stringify({ success: true, workItem: data?.workItem ?? null }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to update intent: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
-    }
+    async (args) => runWithMcpToolCard("coordination_update_intent", args, async () => {
+      const { projectId, workItemId } = readCoordinationIds();
+      const body = {
+        projectId,
+        workItemId,
+        summary: args?.summary ?? void 0,
+        status: args?.status ?? void 0,
+        plannedFiles: args?.plannedFiles ?? void 0,
+        activeFiles: args?.activeFiles ?? void 0,
+        doneFiles: args?.doneFiles ?? void 0,
+        waitingOnFiles: args?.waitingOnFiles ?? void 0,
+        leaseMs: args?.leaseMs ?? void 0
+      };
+      const data = await postJson("/v1/coordination/work-items/update", body);
+      return textToolResult(JSON.stringify({ success: true, workItem: data?.workItem ?? null }, null, 2), false);
+    })
   );
   mcp.registerTool(
     "ledger_claim",
@@ -8430,8 +8616,7 @@ ${String(st.stdout || "").trim()}`
       }
     },
     async (args) => {
-      const callId = emitFlockbayMcpToolCall("ledger_claim", args);
-      try {
+      return await runWithMcpToolCard("ledger_claim", args, async () => {
         const { projectId, workItemId } = readCoordinationIds();
         if (args?.summary !== void 0 || args?.status !== void 0 || args?.plannedFiles !== void 0) {
           await postJson("/v1/coordination/work-items/update", {
@@ -8467,9 +8652,7 @@ ${String(st.stdout || "").trim()}`
         const data = await postJson("/v1/coordination/work-items/claim-files", { projectId, workItemId, ...payloadArgs });
         const ok = Boolean(data?.success);
         if (!ok) {
-          const result2 = textToolResult(JSON.stringify(data ?? { success: false, error: "claim_failed" }, null, 2), true);
-          emitFlockbayMcpToolResult(callId, result2, true);
-          return result2;
+          return textToolResult(JSON.stringify(data ?? { success: false, error: "claim_failed" }, null, 2), true);
         }
         const claimedFiles = Array.isArray(data?.claimedFiles) ? data.claimedFiles : files;
         const claimedSet = new Set(claimedFiles.map((v) => String(v || "").trim()).filter(Boolean));
@@ -8501,7 +8684,6 @@ ${String(st.stdout || "").trim()}`
             ),
             true
           );
-          emitFlockbayMcpToolResult(callId, result2, true);
           return result2;
         }
         try {
@@ -8525,13 +8707,8 @@ ${String(st.stdout || "").trim()}`
           ),
           false
         );
-        emitFlockbayMcpToolResult(callId, result, false);
         return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to claim via ledger: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
+      });
     }
   );
   mcp.registerTool(
@@ -8548,8 +8725,7 @@ ${String(st.stdout || "").trim()}`
       }
     },
     async (args) => {
-      const callId = emitFlockbayMcpToolCall("ledger_release", args);
-      try {
+      return await runWithMcpToolCard("ledger_release", args, async () => {
         const { projectId, workItemId } = readCoordinationIds();
         const data = await postJson("/v1/coordination/work-items/list", { projectId });
         const items = Array.isArray(data?.workItems) ? data.workItems : [];
@@ -8598,14 +8774,8 @@ ${String(st.stdout || "").trim()}`
         } catch (err) {
           logger.debug("[flockbayMCP] Failed to revoke local write tokens:", err);
         }
-        const result = textToolResult(JSON.stringify({ success: true, workItem: updated?.workItem ?? null }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to release ledger entry: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
+        return textToolResult(JSON.stringify({ success: true, workItem: updated?.workItem ?? null }, null, 2), false);
+      });
     }
   );
   mcp.registerTool(
@@ -8619,8 +8789,7 @@ ${String(st.stdout || "").trim()}`
       }
     },
     async (args) => {
-      const callId = emitFlockbayMcpToolCall("coordination_check_files", args);
-      try {
+      return await runWithMcpToolCard("coordination_check_files", args, async () => {
         const { projectId, workItemId } = readCoordinationIds();
         const includeSelf = args?.includeSelf !== false;
         const rawFiles = Array.isArray(args?.files) ? args.files : [];
@@ -8675,14 +8844,8 @@ ${String(st.stdout || "").trim()}`
           const otherOwners = owners.filter((o) => !o.isSelf);
           return { filePath, available: otherOwners.length === 0, owners };
         });
-        const result = textToolResult(JSON.stringify({ projectId, files: out }, null, 2), false);
-        emitFlockbayMcpToolResult(callId, result, false);
-        return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to check files: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
+        return textToolResult(JSON.stringify({ projectId, files: out }, null, 2), false);
+      });
     }
   );
   mcp.registerTool(
@@ -8697,8 +8860,7 @@ ${String(st.stdout || "").trim()}`
       }
     },
     async (args) => {
-      const callId = emitFlockbayMcpToolCall("coordination_claim_files", args);
-      try {
+      return await runWithMcpToolCard("coordination_claim_files", args, async () => {
         const { projectId, workItemId } = readCoordinationIds();
         const rawFiles = Array.isArray(args?.files) ? args.files : [];
         const files = rawFiles.map((v) => String(v || "").trim().replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/^\/+/, "")).filter((v) => Boolean(v));
@@ -8726,9 +8888,7 @@ ${String(st.stdout || "").trim()}`
         };
         const data = await postJson("/v1/coordination/work-items/claim-files", body);
         if (!data?.success) {
-          const result2 = textToolResult(JSON.stringify(data ?? { success: false, error: "claim_failed" }, null, 2), true);
-          emitFlockbayMcpToolResult(callId, result2, true);
-          return result2;
+          return textToolResult(JSON.stringify(data ?? { success: false, error: "claim_failed" }, null, 2), true);
         }
         const claimedFiles = Array.isArray(data?.claimedFiles) ? data.claimedFiles : files;
         const claimedSet = new Set(claimedFiles.map((v) => String(v || "").trim()).filter(Boolean));
@@ -8760,7 +8920,6 @@ ${String(st.stdout || "").trim()}`
             ),
             true
           );
-          emitFlockbayMcpToolResult(callId, result2, true);
           return result2;
         }
         try {
@@ -8784,13 +8943,8 @@ ${String(st.stdout || "").trim()}`
           ),
           false
         );
-        emitFlockbayMcpToolResult(callId, result, false);
         return result;
-      } catch (err) {
-        const result = textToolResult(`Failed to claim files: ${err instanceof Error ? err.message : String(err)}`, true);
-        emitFlockbayMcpToolResult(callId, result, true);
-        return result;
-      }
+      });
     }
   );
   mcp.registerTool(
@@ -8819,7 +8973,7 @@ ${String(st.stdout || "").trim()}`
         content.push({ type: "image", data: img.base64, mimeType: img.mimeType });
       });
       return { content, isError: false };
-    })
+    }, { passthroughImagesToModel: true })
   );
   mcp.registerTool(
     "read_images",
@@ -8938,7 +9092,7 @@ ${String(st.stdout || "").trim()}`
           isError: true
         };
       }
-    })
+    }, { passthroughImagesToModel: true })
   );
   mcp.registerTool("unreal_latest_screenshots", {
     title: "Latest Unreal Screenshots (Validation)",
@@ -9780,10 +9934,10 @@ ${String(st.stdout || "").trim()}`
       paths: z.array(z.string()).optional().describe('Root content paths to search (default ["/Game"]).'),
       includeWarnings: z.boolean().optional().describe("Include warnings in the per-blueprint messages list (default true)."),
       limit: z.number().int().positive().optional().describe("Max number of blueprints to compile (default 500, max 10000)."),
-      timeoutMs: z.number().int().positive().optional().describe("Socket timeout in ms (default 60000).")
+      timeoutMs: z.number().int().positive().optional().describe("Socket timeout in ms (default 30000, max 30000).")
     }
   }, async (args) => runWithMcpToolCard("unreal_mcp_compile_blueprints_all", args, async () => {
-    const timeoutMs = args.timeoutMs ?? 6e4;
+    const timeoutMs = Math.min(3e4, Math.max(250, Number(args.timeoutMs ?? 3e4) || 3e4));
     unrealEditorSupervisor.noteUnrealActivity();
     try {
       const params = {};
@@ -9814,10 +9968,10 @@ ${String(st.stdout || "").trim()}`
     title: "Unreal Save All (UnrealMCP)",
     description: "Save all dirty packages (maps + content) in the running Unreal Editor without prompting. Intended to prevent leaving editor changes unsaved. Fails if PIE is running.",
     inputSchema: {
-      timeoutMs: z.number().int().positive().optional().describe("Socket timeout in ms (default 60000).")
+      timeoutMs: z.number().int().positive().optional().describe("Socket timeout in ms (default 30000, max 30000).")
     }
   }, async (args) => runWithMcpToolCard("unreal_mcp_save_all", args, async () => {
-    const timeoutMs = args?.timeoutMs ?? 6e4;
+    const timeoutMs = Math.min(3e4, Math.max(250, Number(args?.timeoutMs ?? 3e4) || 3e4));
     unrealEditorSupervisor.noteUnrealActivity();
     try {
       const response = await sendUnrealMcpTcpCommand({ type: "save_all", params: {}, timeoutMs });
@@ -10592,6 +10746,8 @@ Fix: ${res.hint}` : "";
       "docs_import",
       "evidence_list",
       "evidence_get",
+      "tool_result_read",
+      "tool_result_query",
       "coordination_update_intent",
       "coordination_check_files",
       "coordination_claim_files",
@@ -11913,6 +12069,410 @@ async function handleConnectVendor(vendor, displayName, flags) {
   }
 }
 
+function readFlag(args, flag) {
+  return args.includes(flag);
+}
+function readArgValue$2(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx < 0) return null;
+  const v = args[idx + 1];
+  return v ? String(v) : null;
+}
+function parseAgentList(args) {
+  const rawAgent = readArgValue$2(args, "--agent") || readArgValue$2(args, "-a");
+  const rawAgents = readArgValue$2(args, "--agents");
+  const wantsAll = readFlag(args, "--all");
+  const split = (raw) => raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  const desired = wantsAll ? ["codex", "claude", "gemini"] : rawAgents ? split(rawAgents) : rawAgent ? [rawAgent.trim().toLowerCase()] : ["codex", "claude", "gemini"];
+  const allow = /* @__PURE__ */ new Set(["codex", "claude", "gemini"]);
+  const agents = desired.filter((a) => allow.has(a));
+  return agents.length > 0 ? agents : ["codex", "claude", "gemini"];
+}
+function permissionModeForAgent(agent) {
+  if (agent === "claude") return "bypassPermissions";
+  return "yolo";
+}
+function nowIsoCompact() {
+  const d = /* @__PURE__ */ new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+async function ensureDaemonRunning({ skipUnreal }) {
+  const ok = await checkIfDaemonRunningAndCleanupStaleState();
+  if (ok) {
+    const same = await isDaemonRunningCurrentCliVersion();
+    if (same) return;
+    logger.debug("[smoke-test] daemon running old CLI version; restarting");
+    await stopDaemon();
+  }
+  logger.debug("[smoke-test] daemon not running; starting via `flockbay start`");
+  const args = ["start"];
+  if (skipUnreal) args.push("--skip-unreal");
+  const child = spawnFlockbayCLI(args, {
+    stdio: "ignore",
+    env: {
+      ...process.env,
+      // Do not pop a browser while smoke-testing.
+      FLOCKBAY_NO_OPEN: "1"
+    },
+    windowsHide: true
+  });
+  child.unref();
+  const deadline = Date.now() + 2e4;
+  while (Date.now() < deadline) {
+    const running = await checkIfDaemonRunningAndCleanupStaleState();
+    if (running) return;
+    await delay(250);
+  }
+  throw new Error("daemon_start_timeout");
+}
+async function createSmokeWorkspaceDir(baseDir) {
+  const root = baseDir?.trim() ? path.resolve(baseDir) : path.join(os.tmpdir(), "flockbay-smoke", nowIsoCompact() + "_" + randomUUID().slice(0, 8));
+  await fs$1.mkdir(root, { recursive: true });
+  const secret = `SMOKE_SECRET_${randomUUID().slice(0, 8)}`;
+  await fs$1.writeFile(path.join(root, "smoke.txt"), `flockbay smoke test
+SMOKE_SECRET=${secret}
+`, "utf8");
+  return { dir: root, secret };
+}
+function isAgentRecord(record) {
+  return record && typeof record === "object" && record.role === "agent";
+}
+function extractTextFromRecord(record) {
+  try {
+    if (!record || typeof record !== "object") return "";
+    const content = record.content;
+    if (!content || typeof content !== "object") return "";
+    if (content.type === "text" && typeof content.text === "string") return content.text;
+    if (content.type === "tool" && Array.isArray(content.tools)) return JSON.stringify(content.tools);
+    if (content.type === "output") {
+      const msg = content?.data?.message;
+      const items = Array.isArray(msg?.content) ? msg.content : [];
+      const texts = [];
+      for (const item of items) {
+        if (item?.type === "text" && typeof item.text === "string") texts.push(item.text);
+      }
+      return texts.join("\n");
+    }
+    return "";
+  } catch {
+    return "";
+  }
+}
+function recordIncludesNeedle(record, needle) {
+  const n = String(needle || "").trim();
+  if (!n) return true;
+  const text = extractTextFromRecord(record);
+  if (text && text.includes(n)) return true;
+  try {
+    return JSON.stringify(record).includes(n);
+  } catch {
+    return false;
+  }
+}
+async function waitForMessage(opts) {
+  const { sessionClient, predicate, timeoutMs } = opts;
+  const deadline = Date.now() + timeoutMs;
+  const existing = await sessionClient.listMessages().catch(() => []);
+  for (const msg of existing) {
+    const record = msg?.content;
+    if (predicate(record)) return msg;
+  }
+  return await new Promise((resolve, reject) => {
+    const onUpdate = (u) => {
+      if (u?.body?.t !== "new-message") return;
+      const record = u?.body?.message?.content;
+      if (!record) return;
+      if (!predicate(record)) return;
+      cleanup();
+      resolve(u?.body?.message);
+    };
+    const tick = () => {
+      if (Date.now() < deadline) return;
+      cleanup();
+      reject(new Error("timeout_waiting_for_message"));
+    };
+    const interval = setInterval(tick, 200);
+    const cleanup = () => {
+      clearInterval(interval);
+      sessionClient.off("update", onUpdate);
+    };
+    sessionClient.on("update", onUpdate);
+  });
+}
+async function runScenario(name, fn) {
+  const startedAtMs = Date.now();
+  try {
+    await fn();
+    return { name, ok: true, startedAtMs, finishedAtMs: Date.now() };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { name, ok: false, error: msg, startedAtMs, finishedAtMs: Date.now() };
+  }
+}
+function tinyPngBase64() {
+  const width = 64;
+  const height = 64;
+  const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+  const crcTable = (() => {
+    const table = new Uint32Array(256);
+    for (let i = 0; i < 256; i += 1) {
+      let c = i;
+      for (let k = 0; k < 8; k += 1) {
+        c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+      }
+      table[i] = c >>> 0;
+    }
+    return table;
+  })();
+  const crc32 = (buf) => {
+    let c = 4294967295;
+    for (let i = 0; i < buf.length; i += 1) {
+      c = crcTable[(c ^ buf[i]) & 255] ^ c >>> 8;
+    }
+    return (c ^ 4294967295) >>> 0;
+  };
+  const chunk = (type, data) => {
+    const typeBuf = Buffer.from(type, "ascii");
+    const lenBuf = Buffer.alloc(4);
+    lenBuf.writeUInt32BE(data.length, 0);
+    const crcBuf = Buffer.alloc(4);
+    const crc = crc32(Buffer.concat([typeBuf, data]));
+    crcBuf.writeUInt32BE(crc, 0);
+    return Buffer.concat([lenBuf, typeBuf, data, crcBuf]);
+  };
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+  const bytesPerPixel = 4;
+  const rowBytes = 1 + width * bytesPerPixel;
+  const raw = Buffer.alloc(rowBytes * height);
+  for (let y = 0; y < height; y += 1) {
+    const rowStart = y * rowBytes;
+    raw[rowStart] = 0;
+    for (let x = 0; x < width; x += 1) {
+      const p = rowStart + 1 + x * bytesPerPixel;
+      raw[p + 0] = 45;
+      raw[p + 1] = 125;
+      raw[p + 2] = 255;
+      raw[p + 3] = 255;
+    }
+  }
+  const compressed = deflateSync(raw, { level: 6 });
+  const png = Buffer.concat([
+    pngSignature,
+    chunk("IHDR", ihdr),
+    chunk("IDAT", compressed),
+    chunk("IEND", Buffer.alloc(0))
+  ]);
+  return png.toString("base64");
+}
+async function safeDeleteDir(dir) {
+  try {
+    await fs$1.rm(dir, { recursive: true, force: true });
+  } catch {
+  }
+}
+async function deleteSession(api, sessionId) {
+  try {
+    await api.deleteSessionById(sessionId);
+  } catch {
+  }
+}
+async function ensureSessionActive(api, sessionId, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const s = await api.getSessionById(sessionId).catch(() => null);
+    if (s?.active) return;
+    await delay(350);
+  }
+  throw new Error("session_not_active");
+}
+async function runSmokeForAgent(agent, args) {
+  const startedAtMs = Date.now();
+  const scenarios = [];
+  const keep = readFlag(args, "--keep");
+  const skipUnreal = !readFlag(args, "--with-unreal");
+  const baseDir = readArgValue$2(args, "--directory") || readArgValue$2(args, "--dir");
+  const timeoutMsRaw = readArgValue$2(args, "--timeout-ms");
+  const timeoutMs = timeoutMsRaw && Number.isFinite(Number(timeoutMsRaw)) ? Number(timeoutMsRaw) : 9e4;
+  let sessionId;
+  let directory;
+  let sessionClient = null;
+  let api = null;
+  try {
+    await ensureDaemonRunning({ skipUnreal });
+    const { auth, machineId } = await ensureMachineAuthOrLogin();
+    api = await ApiClient.create(auth);
+    const { dir, secret } = await createSmokeWorkspaceDir(baseDir);
+    directory = dir;
+    const sessionMeta = {
+      path: dir,
+      machineId,
+      flavor: agent,
+      createdBy: "smoke-test",
+      tag: `smoke_${agent}_${nowIsoCompact()}`
+    };
+    const session = await api.createSession({ metadata: sessionMeta, state: null });
+    sessionId = session.id;
+    if (!sessionId) throw new Error("create_session_failed");
+    const spawnResult = await spawnDaemonSession(dir, sessionId, agent);
+    if (!spawnResult?.success) {
+      const msg = String(spawnResult?.error || "spawn_failed");
+      throw new Error(msg);
+    }
+    sessionClient = api.sessionSyncClient(session);
+    await sessionClient.connectAndWait(15e3);
+    await ensureSessionActive(api, sessionId, 25e3);
+    const permissionMode = permissionModeForAgent(agent);
+    scenarios.push(await runScenario("basic-message", async () => {
+      const token = `SMOKE_OK_${agent}_${randomUUID().slice(0, 6)}`;
+      sessionClient.sendUserText(`Reply with exactly: ${token}`, { permissionMode });
+      await waitForMessage({
+        sessionClient,
+        predicate: (r) => isAgentRecord(r) && recordIncludesNeedle(r, token),
+        timeoutMs
+      });
+    }));
+    scenarios.push(await runScenario("tool-search", async () => {
+      const token = `TOOL_SEARCH_OK_${randomUUID().slice(0, 6)}`;
+      sessionClient.sendUserText(
+        [
+          "Read the file `smoke.txt` in the project directory using MCP tools (e.g. `read_file_chunk` or `search`).",
+          "Find the value after `SMOKE_SECRET=`.",
+          "",
+          `Reply with two lines exactly:`,
+          `1) SMOKE_SECRET=<value>`,
+          `2) ${token}`
+        ].join("\n"),
+        { permissionMode }
+      );
+      await waitForMessage({
+        sessionClient,
+        predicate: (r) => isAgentRecord(r) && recordIncludesNeedle(r, `SMOKE_SECRET=${secret}`) && recordIncludesNeedle(r, token),
+        timeoutMs
+      });
+    }));
+    scenarios.push(await runScenario("image-attachment", async () => {
+      const token = `IMAGE_OK_${randomUUID().slice(0, 6)}`;
+      const base64 = tinyPngBase64();
+      sessionClient.sendUserText(
+        `Describe the attached image in one short sentence, then reply with exactly: ${token}`,
+        {
+          permissionMode,
+          attachments: {
+            images: [{ mimeType: "image/png", base64, name: "smoke.png" }]
+          }
+        }
+      );
+      const msg = await waitForMessage({
+        sessionClient,
+        predicate: (r) => isAgentRecord(r) && (recordIncludesNeedle(r, token) || agent === "codex" && recordIncludesNeedle(r, "image-attachment-missing") || recordIncludesNeedle(r, "Could not process image") || recordIncludesNeedle(r, "messages.") || recordIncludesNeedle(r, "invalid_request_error")),
+        timeoutMs
+      });
+      const record = msg?.content;
+      if (agent === "codex" && recordIncludesNeedle(record, "image-attachment-missing")) {
+        throw new Error("image-attachment-missing (Codex did not receive images; check latest_user_images tool + vision support)");
+      }
+      if (recordIncludesNeedle(record, "Could not process image") || recordIncludesNeedle(record, "invalid_request_error")) {
+        throw new Error("provider_image_invalid (image rejected by provider; check base64/mimeType pipeline)");
+      }
+    }));
+    const ok = scenarios.every((s) => s.ok);
+    return {
+      agent,
+      ok,
+      sessionId,
+      directory,
+      scenarios,
+      startedAtMs,
+      finishedAtMs: Date.now()
+    };
+  } finally {
+    if (sessionClient) {
+      try {
+        sessionClient.removeAllListeners();
+      } catch {
+      }
+      try {
+        sessionClient.close();
+      } catch {
+      }
+    }
+    if (sessionId) {
+      if (!keep) {
+        try {
+          await stopDaemonSession(sessionId);
+        } catch {
+        }
+      }
+    }
+    if (directory && !keep) {
+      await safeDeleteDir(directory);
+    }
+    if (sessionId && api && !keep) {
+      await deleteSession(api, sessionId);
+    }
+  }
+}
+function showHelp() {
+  console.log(`
+${chalk.bold("flockbay smoke-test")} - end-to-end smoke tests for daemon + session runtime + MCP tools
+
+Usage:
+  flockbay smoke-test [--all] [--agent codex|claude|gemini] [--agents codex,claude] [--directory <path>]
+
+Options:
+  --all                 Run all agents (default)
+  --agent, -a           Run a single agent
+  --agents              Comma-separated list of agents
+  --directory, --dir    Directory to run the session in (defaults to a temp folder)
+  --timeout-ms          Per-scenario timeout (default 90000)
+  --keep                Do not stop session or delete temp dir
+  --json                Write results JSON to a file
+  --with-unreal         Allow Unreal bridge prompts (off by default)
+`);
+}
+async function handleSmokeTestCommand(args) {
+  if (args.includes("--help") || args.includes("-h") || args.includes("help")) {
+    showHelp();
+    return;
+  }
+  const agents = parseAgentList(args);
+  const outPath = readArgValue$2(args, "--json");
+  console.log(chalk.bold("\nFlockbay smoke test\n"));
+  console.log(chalk.gray(`Server:  ${configuration.serverUrl}`));
+  console.log(chalk.gray(`Profile: ${configuration.profile}`));
+  console.log(chalk.gray(`Agents:  ${agents.join(", ")}`));
+  console.log("");
+  const results = [];
+  for (const agent of agents) {
+    console.log(chalk.bold(`== ${agent} ==`));
+    const r = await runSmokeForAgent(agent, args);
+    results.push(r);
+    for (const s of r.scenarios) {
+      if (s.ok) console.log(chalk.green(`  \u2713 ${s.name}`));
+      else console.log(chalk.red(`  \u2717 ${s.name}: ${s.error || "failed"}`));
+    }
+    console.log(r.ok ? chalk.green("  PASS\n") : chalk.red("  FAIL\n"));
+  }
+  const allOk = results.every((r) => r.ok);
+  if (outPath) {
+    const abs = path.resolve(outPath);
+    await fs$1.mkdir(path.dirname(abs), { recursive: true });
+    await fs$1.writeFile(abs, JSON.stringify({ ok: allOk, results }, null, 2) + "\n", "utf8");
+    console.log(chalk.gray(`Wrote: ${abs}`));
+  }
+  if (!allOk) {
+    process.exitCode = 1;
+  }
+}
+
 function readArgValue$1(args, key) {
   const idx = args.indexOf(key);
   if (idx === -1) return null;
@@ -12636,6 +13196,16 @@ async function authAndSetupMachineIfNeeded() {
       process.exit(1);
     }
     return;
+  } else if (subcommand === "smoke-test") {
+    try {
+      await ensureProdServerWhenLocalDevUnreachable();
+      await handleSmokeTestCommand(args.slice(1));
+    } catch (error) {
+      console.error(chalk.red("Smoke test failed:"), error instanceof Error ? error.message : "Unknown error");
+      if (process.env.DEBUG) console.error(error);
+      process.exit(1);
+    }
+    return;
   } else if (subcommand === "start") {
     const startArgs = args.slice(1);
     if (startArgs.includes("--help") || startArgs.includes("-h") || startArgs.includes("help")) {
@@ -12678,7 +13248,7 @@ ${engineRoot}`, {
   } else if (subcommand === "codex") {
     try {
       await chdirToNearestUprojectRootIfPresent();
-      const { runCodex } = await import('./runCodex-Ujz1z7Tp.mjs');
+      const { runCodex } = await import('./runCodex-B0JRo8YP.mjs');
       let startedBy = void 0;
       let sessionId = void 0;
       for (let i = 1; i < args.length; i++) {
@@ -12780,7 +13350,7 @@ ${engineRoot}`, {
     }
     try {
       await chdirToNearestUprojectRootIfPresent();
-      const { runGemini } = await import('./runGemini-BbdMLMnn.mjs');
+      const { runGemini } = await import('./runGemini-DO9xzjyY.mjs');
       let startedBy = void 0;
       let sessionId = void 0;
       for (let i = 1; i < args.length; i++) {