flockbay 0.10.15 → 0.10.17

package/dist/{index--o4BPz5o.cjs → index-BxBuBx7C.cjs}

@@ -3,7 +3,7 @@
 var chalk = require('chalk');
 var os = require('node:os');
 var node_crypto = require('node:crypto');
-var types = require('./types-C-jnUdn_.cjs');
+var types = require('./types-CGQhv7Z-.cjs');
 var node_child_process = require('node:child_process');
 var path = require('node:path');
 var node_readline = require('node:readline');
@@ -15,20 +15,17 @@ var ink = require('ink');
 var React = require('react');
 var node_url = require('node:url');
 var axios = require('axios');
-require('node:events');
+var node_events = require('node:events');
 require('socket.io-client');
-var tweetnacl = require('tweetnacl');
 var child_process = require('child_process');
 var crypto = require('crypto');
 var path$1 = require('path');
 var os$1 = require('os');
 require('node:net');
-require('expo-server-sdk');
 var fs$3 = require('fs');
 var psList = require('ps-list');
 var spawn = require('cross-spawn');
 var tmp = require('tmp');
-var qrcode = require('qrcode-terminal');
 var open = require('open');
 var fastify = require('fastify');
 var z = require('zod');
@@ -36,6 +33,7 @@ var fastifyTypeProviderZod = require('fastify-type-provider-zod');
 var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
 var node_http = require('node:http');
 var streamableHttp_js = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
+require('tweetnacl');
 var http = require('http');
 var util = require('util');
 
@@ -298,27 +296,68 @@ const PLATFORM_SYSTEM_PROMPT = trimIdent(`
 
   UnrealMCP capability hygiene (avoid guessing):
   - UnrealMCP command sets can differ by plugin build/version.
-  - When starting UnrealMCP work in a session (or after any "Unknown command" error), run \`mcp__flockbay__unreal_mcp_command\` with \`type: "get_plugin_info"\` and use only the returned \`commands\` list.
+  - When starting UnrealMCP work in a session (or after any "Unknown command" error), prefer:
+    - \`mcp__flockbay__unreal_mcp_list_capabilities\` (fast: build info + supported commands + capability flags)
+    - or \`mcp__flockbay__unreal_mcp_command\` with \`type: "get_plugin_info"\` (supported commands list)
+  - When you're unsure about required params or accepted aliases for a command, use:
+    - \`mcp__flockbay__unreal_mcp_get_command_schema\` (returns required keys + examples for the running plugin build)
   - This is guidance (not a hard block): you may try a command, but if it\u2019s not supported, immediately switch to the nearest supported command instead of guessing more commands.
 
+  UnrealMCP asset placement (avoid guessing \`/Game/...\` paths):
+  - If the user asks to place assets from the project\u2019s \`/Content\` folder, do NOT guess object paths.
+  - Use \`mcp__flockbay__unreal_mcp_search_assets\` to find the asset\u2019s \`objectPath\`, and optionally \`mcp__flockbay__unreal_mcp_get_asset_info\` to confirm its class.
+  - Place it via \`mcp__flockbay__unreal_mcp_place_asset\` (supports StaticMesh + Blueprint assets).
+  - If the user says \u201Cuse an asset pack\u201D, you may first call \`mcp__flockbay__unreal_mcp_list_asset_packs\` to discover top-level \`/Game\` folders, then search within the pack root.
+
+  Unreal spatial intent (stop guessing \u201Chere/there\u201D):
+  - For \u201Cput X here/there / in front of me / on that surface\u201D, prefer these primitives:
+    - \`mcp__flockbay__unreal_mcp_get_editor_context\` (map + selection + editor camera)
+    - \`mcp__flockbay__unreal_mcp_get_player_context\` (PIE player pawn + camera)
+    - \`mcp__flockbay__unreal_mcp_raycast_from_camera\` (turn \u201Cthat surface\u201D into hit location + normal)
+    - \`mcp__flockbay__unreal_mcp_raycast_down\` (drop-to-ground)
+    - \`mcp__flockbay__unreal_mcp_get_actor_transform\` / \`mcp__flockbay__unreal_mcp_get_actor_bounds\`
+  - If the user wants a one-call helper, use:
+    - \`mcp__flockbay__unreal_place_asset_relative\` (place asset relative to selection/camera/player/hit)
+    - \`mcp__flockbay__unreal_spawn_actor_relative\` (spawn actor relative to selection/camera/player/hit)
+
   UnrealMCP PIE safety (avoid editor crashes):
   - Before running editor-world mutation commands (spawn/delete actors, set properties/transforms, spawn Blueprint actors), check \`get_play_in_editor_status\`.
   - If PIE is running/queued, stop it (\`stop_play_in_editor\`) before retrying the mutation.
 
+    Unreal verify + diagnose (recommended validation after changes):
+    - After making changes (especially content/Blueprint changes), prefer this sequence:
+      1) \`mcp__flockbay__unreal_mcp_compile_blueprints_all\`
+      2) \`mcp__flockbay__unreal_mcp_map_check\`
+      3) If C++ exists or was edited: \`mcp__flockbay__unreal_build_project\`
+      4) \`mcp__flockbay__unreal_smoke_test\` (PIE windowed + screenshot validation)
+    - If any step fails: stop, report the structured failures, and propose the smallest fix.
+    - After the change is validated and before concluding, save editor changes:
+      - Prefer \`mcp__flockbay__unreal_mcp_save_all\` to save all dirty packages.
+      - Or use \`mcp__flockbay__unreal_mcp_command\` with \`type: "save_all"\` to save all dirty packages.
+      - If \`save_all\` reports still-dirty packages, do not end the request; resolve the save issue and retry.
+
   UnrealMCP editor health (detect crashes/offline):
   - If UnrealMCP requests fail to connect or time out, run the health check tool (if available) to determine whether the editor is reachable.
   - Treat "not reachable" as: Unreal Editor is closed/crashed/hung OR UnrealMCP plugin is disabled. The minimal fix is to reopen/restart the editor and enable the plugin.
 
-  ## B) Screenshots (via UnrealMCP)
-  Use UnrealMCP when the user asks for:
-  - a screenshot of the editor viewport
-  - visual proof of an in-editor change
+  Unreal Editor relaunch (manual, never auto-restart):
+  - The platform may detect that Unreal Editor crashed/unreachable and will automatically abort your current run and post a chat message.
+  - When that happens: STOP UnrealMCP calls, fix the project as needed, then (only when ready) relaunch Unreal Editor with \`mcp__flockbay__unreal_editor_launch\`.
+  - Do not \u201Cauto-restart\u201D in a loop. Relaunch is a deliberate action after fixes.
+
+    ## B) Screenshots (via UnrealMCP)
+    Use UnrealMCP when the user asks for:
+    - a screenshot of the editor viewport
+    - visual validation of an in-editor change
 
   How:
   - Use \`mcp__flockbay__unreal_mcp_command\` with \`type: "take_screenshot"\`.
   - Default save path is \`<Project>/Saved/Screenshots/Flockbay/\` (auto-generated filename). Optional params: \`filepath\` (absolute or relative filename) and/or \`filename\` (base name).
 
   Do not use screenshots as a default fallback for editor queries (e.g. \u201Clist actors\u201D).
+  Do not treat \u201Ctook a screenshot\u201D as \u201Cdone\u201D:
+  - Screenshots are primarily for YOU (the agent) to validate the change.
+  - If the screenshot does not clearly confirm the requirement, continue iterating (or run a different verify tool).
 
   # Non\u2011negotiables
 
@@ -337,9 +376,10 @@ const PLATFORM_SYSTEM_PROMPT = trimIdent(`
   # Evidence strategy (how to validate)
 
   - Choose the lightest evidence that answers the user\u2019s request.
-  - Prefer \u201Cone proof\u201D over \u201Cmany proofs\u201D.
+  - Prefer \u201Cone validation\u201D over \u201Cmany validations\u201D.
   - If you need visual confirmation, ask for or produce a screenshot explicitly (don\u2019t sneak it in).
-  - Always view the resulting image/proof after creating one, and judge the result for yourself if possible.
+  - Always view the resulting image after creating one, and judge the result for yourself (not just for the user).
+  - If the image is ambiguous or doesn\u2019t show the requirement, say what\u2019s missing and keep going (don\u2019t end the request prematurely).
 
   # Session hygiene
 
@@ -858,7 +898,7 @@ async function claudeLocalLauncher(session) {
       }
       await abort();
     }
-    session.client.rpcHandlerManager.registerHandler("abort", doAbort);
+    session.client.rpcHandlerManager.registerHandler("cancel-generation", doAbort);
     session.client.rpcHandlerManager.registerHandler("switch", doSwitch);
     session.queue.setOnMessage((message, mode) => {
       doSwitch();
@@ -906,8 +946,6 @@ async function claudeLocalLauncher(session) {
     }
   } finally {
     exutFuture.resolve(void 0);
-    session.client.rpcHandlerManager.registerHandler("abort", async () => {
-    });
     session.client.rpcHandlerManager.registerHandler("switch", async () => {
     });
     session.queue.setOnMessage(null);
@@ -1234,7 +1272,7 @@ function buildDaemonSafeEnv(baseEnv, binPath) {
   env[pathKey] = [...prepend, ...existingParts].join(pathSep);
   return env;
 }
-const __filename$1 = node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index--o4BPz5o.cjs', document.baseURI).href)));
+const __filename$1 = node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index-BxBuBx7C.cjs', document.baseURI).href)));
 const __dirname$1 = path.join(__filename$1, "..");
 function getGlobalClaudeVersion(claudeExecutable) {
   try {
@@ -1913,6 +1951,139 @@ function getLatestUserImages() {
   return latestUserImages;
 }
 
+function uniqPush(into, seen, value) {
+  const v = value.trim();
+  if (!v) return;
+  if (seen.has(v)) return;
+  seen.add(v);
+  into.push(v);
+}
+function normalizeFilePathToken(token) {
+  return token.trim().replace(/^['"`]+/, "").replace(/['"`]+$/, "").replace(/[),.;:'"`]+$/, "").trim();
+}
+function resolveCandidatePath(candidate, cwd) {
+  const raw = normalizeFilePathToken(candidate);
+  if (!raw) return raw;
+  if (raw.startsWith("~/")) {
+    const home = process.env.HOME || process.env.USERPROFILE || "";
+    if (home) return path.join(home, raw.slice(2));
+  }
+  return path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+}
+function isImageBlock(block) {
+  if (!block || typeof block !== "object") return false;
+  if (block.type !== "image") return false;
+  if (typeof block.data === "string" && block.data.length > 0) return true;
+  if (block.source && typeof block.source === "object" && typeof block.source.data === "string" && block.source.data.length > 0) return true;
+  return false;
+}
+function tryParseJsonObjectWithViews(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  try {
+    const direct = JSON.parse(trimmed);
+    if (direct && typeof direct === "object" && Array.isArray(direct.views)) return direct;
+  } catch {
+  }
+  for (let i = trimmed.length - 1; i >= 0; i -= 1) {
+    if (trimmed[i] !== "{") continue;
+    const candidate = trimmed.slice(i);
+    try {
+      const parsed = JSON.parse(candidate);
+      if (parsed && typeof parsed === "object" && Array.isArray(parsed.views)) return parsed;
+    } catch {
+    }
+  }
+  return null;
+}
+function extractScreenshotViewsFromText(text, cwd) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const re = /(?:^|[\s"'(])(?:-\s*)?([^\s"'()]*Saved[\\/]+Screenshots[\\/]+Flockbay[\\/]+[^\s"'()]+\.(?:png|jpg|jpeg))/gi;
+  for (const match of text.matchAll(re)) {
+    const token = String(match[1] || "");
+    const resolved = resolveCandidatePath(token, cwd);
+    if (!resolved) continue;
+    if (!resolved.includes(`${path.sep}Saved${path.sep}Screenshots${path.sep}Flockbay${path.sep}`) && !resolved.includes("Saved/Screenshots/Flockbay/") && !resolved.includes("Saved\\Screenshots\\Flockbay\\")) {
+      continue;
+    }
+    uniqPush(out, seen, resolved);
+  }
+  if (out.length === 0 && (text.includes("Saved/Screenshots/Flockbay") || text.includes("Saved\\Screenshots\\Flockbay"))) {
+    const filenameRe = /(?:^|[\s"'(\\/])(?:-\s*)?(Flockbay_[A-Za-z0-9_.-]+\.(?:png|jpg|jpeg))/gi;
+    for (const match of text.matchAll(filenameRe)) {
+      const filename = normalizeFilePathToken(String(match[1] || ""));
+      if (!filename) continue;
+      const rel = path.join("Saved", "Screenshots", "Flockbay", filename);
+      const resolved = resolveCandidatePath(rel, cwd);
+      uniqPush(out, seen, resolved);
+    }
+  }
+  return out;
+}
+function extractViewsFromParsedJson(parsed, cwd) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const views = Array.isArray(parsed?.views) ? parsed.views : [];
+  for (const v of views) {
+    const p = typeof v?.path === "string" ? v.path : "";
+    if (!p.trim()) continue;
+    uniqPush(out, seen, resolveCandidatePath(p, cwd));
+  }
+  return out;
+}
+function extractFromContentBlocks(content, cwd) {
+  const texts = [];
+  let hasImages = false;
+  for (const block of content) {
+    if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {
+      texts.push(block.text);
+    }
+    if (!hasImages && isImageBlock(block)) hasImages = true;
+  }
+  const text = texts.join("\n");
+  const parsed = tryParseJsonObjectWithViews(text);
+  const jsonPaths = parsed ? extractViewsFromParsedJson(parsed, cwd) : [];
+  const pathMatches = extractScreenshotViewsFromText(text, cwd);
+  const combined = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const p of jsonPaths) uniqPush(combined, seen, p);
+  for (const p of pathMatches) uniqPush(combined, seen, p);
+  return { paths: combined, hasImages };
+}
+function detectScreenshotsForGate(args) {
+  const cwd = args.cwd && args.cwd.trim().length > 0 ? args.cwd : process.cwd();
+  const output = args.output;
+  if (Array.isArray(output)) {
+    const extracted = extractFromContentBlocks(output, cwd);
+    return { paths: extracted.paths, hasImageBlocks: extracted.hasImages };
+  }
+  if (output && typeof output === "object" && Array.isArray(output.content)) {
+    const extracted = extractFromContentBlocks(output.content, cwd);
+    return { paths: extracted.paths, hasImageBlocks: extracted.hasImages };
+  }
+  if (output && typeof output === "object" && Array.isArray(output.views)) {
+    return { paths: extractViewsFromParsedJson(output, cwd), hasImageBlocks: false };
+  }
+  const candidates = [
+    typeof output === "string" ? output : null,
+    typeof output?.stdout === "string" ? output.stdout : null,
+    typeof output?.stderr === "string" ? output.stderr : null,
+    typeof output?.output === "string" ? output.output : null,
+    typeof output?.message === "string" ? output.message : null
+  ];
+  const combinedText = candidates.filter((v) => typeof v === "string" && v.trim().length > 0).join("\n");
+  if (!combinedText) return { paths: [], hasImageBlocks: false };
+  const parsed = tryParseJsonObjectWithViews(combinedText);
+  const jsonPaths = parsed ? extractViewsFromParsedJson(parsed, cwd) : [];
+  const pathMatches = extractScreenshotViewsFromText(combinedText, cwd);
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const p of jsonPaths) uniqPush(out, seen, p);
+  for (const p of pathMatches) uniqPush(out, seen, p);
+  return { paths: out, hasImageBlocks: false };
+}
+
 function buildClaudeUserContent(text, images) {
   const cleanText = String(text ?? "").trim();
   if (images.length === 0) return cleanText;
@@ -2023,6 +2194,61 @@ async function claudeRemote(opts) {
     }
   };
   let messages = new PushableAsyncIterable();
+  const screenshotGate = {
+    paths: [],
+    seen: /* @__PURE__ */ new Set(),
+    hasImageBlocks: false,
+    inAutoReview: false
+  };
+  const resetScreenshotGateForTurn = () => {
+    screenshotGate.paths = [];
+    screenshotGate.seen.clear();
+    screenshotGate.hasImageBlocks = false;
+    screenshotGate.inAutoReview = false;
+  };
+  const collectScreenshotsForGate = (output) => {
+    if (!output) return;
+    const detected = detectScreenshotsForGate({ output, cwd: opts.path });
+    if (detected.paths.length === 0) return;
+    if (detected.hasImageBlocks) screenshotGate.hasImageBlocks = true;
+    for (const p of detected.paths) {
+      const trimmed = String(p || "").trim();
+      if (!trimmed) continue;
+      if (screenshotGate.seen.has(trimmed)) continue;
+      screenshotGate.seen.add(trimmed);
+      screenshotGate.paths.push(trimmed);
+    }
+  };
+  const buildScreenshotAutoReviewPrompt = (paths) => {
+    const unique = Array.from(new Set(paths.map((p) => String(p || "").trim()).filter(Boolean)));
+    const toolArgs = JSON.stringify(
+      {
+        paths: unique,
+        limit: unique.length,
+        upload: false,
+        includeToolImages: true
+      },
+      null,
+      2
+    );
+    return trimIdent(`
+            You just generated ${unique.length} screenshot${unique.length === 1 ? "" : "s"}.
+
+            Before doing anything else, call \`mcp__flockbay__read_images\` with:
+            ${toolArgs}
+
+            Then visually inspect EVERY screenshot and report (this is for YOUR validation, not ceremony):
+            1) List 2\u20135 concrete acceptance criteria for the user's request.
+            2) One short bullet per image ("Image N: ...") describing what you see.
+            3) For each acceptance criterion: mark it as Verified / Not visible / Failed based ONLY on the screenshots.
+               - If "Not visible", say what evidence is missing.
+               - If "Failed", say what is wrong.
+            4) If anything is not Verified: state the next tool/action you will take to fix or validate it (do not claim completion yet).
+
+            Do not run any other tools in this step.
+        `);
+  };
+  resetScreenshotGateForTurn();
   const initialParsed = extractUserImagesMarker(initial.message);
   const initialImages = initialParsed.hasImages ? getLatestUserImages().slice(0, initialParsed.count) : [];
   messages.push({
@@ -2097,6 +2323,17 @@ async function claudeRemote(opts) {
       if (message.type === "result") {
         updateThinking(false);
         types.logger.debug("[claudeRemote] Result received, exiting claudeRemote");
+        if (!screenshotGate.inAutoReview && screenshotGate.paths.length > 0 && !screenshotGate.hasImageBlocks) {
+          screenshotGate.inAutoReview = true;
+          const reviewPrompt = buildScreenshotAutoReviewPrompt(screenshotGate.paths);
+          messages.push({
+            type: "user",
+            message: { role: "user", content: reviewPrompt }
+          });
+          updateThinking(true);
+          continue;
+        }
+        screenshotGate.inAutoReview = false;
         if (isCompactCommand) {
           types.logger.debug("[claudeRemote] Compaction completed");
           if (opts.onCompletionEvent) {
@@ -2111,14 +2348,19 @@ async function claudeRemote(opts) {
           return;
         }
         mode = next.mode;
+        resetScreenshotGateForTurn();
         const parsed = extractUserImagesMarker(next.message);
         const nextImages = parsed.hasImages ? getLatestUserImages().slice(0, parsed.count) : [];
         messages.push({ type: "user", message: { role: "user", content: buildClaudeUserContent(parsed.text, nextImages) } });
+        updateThinking(true);
       }
       if (message.type === "user") {
         const msg = message;
         if (msg.message.role === "user" && Array.isArray(msg.message.content)) {
           for (let c of msg.message.content) {
+            if (c.type === "tool_result") {
+              collectScreenshotsForGate(c.content ?? c);
+            }
             if (c.type === "tool_result" && c.tool_use_id && opts.isAborted(c.tool_use_id)) {
               types.logger.debug("[claudeRemote] Tool aborted, exiting claudeRemote");
               return;
@@ -2665,11 +2907,14 @@ ${next}`
     }
     this.pendingRequests.clear();
     this.session.client.updateAgentState((currentState) => {
-      const pendingRequests = currentState.requests || {};
-      const completedRequests = { ...currentState.completedRequests };
+      const pendingRaw = currentState?.requests;
+      const pendingRequests = pendingRaw && typeof pendingRaw === "object" ? pendingRaw : {};
+      const completedRaw = currentState?.completedRequests;
+      const completedRequests = completedRaw && typeof completedRaw === "object" ? { ...completedRaw } : {};
       for (const [id, request] of Object.entries(pendingRequests)) {
+        const reqObj = request && typeof request === "object" ? request : { value: request };
         completedRequests[id] = {
-          ...request,
+          ...reqObj,
           completedAt: Date.now(),
           status: "canceled",
           reason: "Session switched to local mode"
@@ -3080,13 +3325,47 @@ class SDKToLogConverter {
   }
 }
 
+class AsyncLock {
+  permits = 1;
+  promiseResolverQueue = [];
+  async inLock(func) {
+    try {
+      await this.lock();
+      return await func();
+    } finally {
+      this.unlock();
+    }
+  }
+  async lock() {
+    if (this.permits > 0) {
+      this.permits = this.permits - 1;
+      return;
+    }
+    await new Promise((resolve) => this.promiseResolverQueue.push(resolve));
+  }
+  unlock() {
+    this.permits += 1;
+    if (this.permits > 1 && this.promiseResolverQueue.length > 0) {
+      throw new Error("this.permits should never be > 0 when there is someone waiting.");
+    } else if (this.permits === 1 && this.promiseResolverQueue.length > 0) {
+      this.permits -= 1;
+      const nextResolver = this.promiseResolverQueue.shift();
+      if (nextResolver) {
+        setTimeout(() => {
+          nextResolver(true);
+        }, 0);
+      }
+    }
+  }
+}
+
 class OutgoingMessageQueue {
   constructor(sendFunction) {
     this.sendFunction = sendFunction;
   }
   queue = [];
   nextId = 1;
-  lock = new types.AsyncLock();
+  lock = new AsyncLock();
   processTimer;
   delayTimers = /* @__PURE__ */ new Map();
   /**
@@ -3271,7 +3550,7 @@ async function postJson(path, token, body) {
   const res = await fetch(`${base}${path}`, {
     method: "POST",
     headers: {
-      Authorization: `Bearer ${token}`,
+      Authorization: `Machine ${token}`,
       "Content-Type": "application/json"
     },
     body: JSON.stringify(body ?? {})
@@ -3413,7 +3692,7 @@ async function claudeRemoteLauncher(session) {
     }
     await abort();
   }
-  session.client.rpcHandlerManager.registerHandler("abort", doAbort);
+  session.client.rpcHandlerManager.registerHandler("cancel-generation", doAbort);
   session.client.rpcHandlerManager.registerHandler("switch", doSwitch);
   const permissionHandler = new PermissionHandler(session);
   const messageQueue = new OutgoingMessageQueue(
@@ -4269,7 +4548,9 @@ async function daemonPost(path, body) {
   }
   try {
     const timeoutRaw = process.env.FLOCKBAY_DAEMON_HTTP_TIMEOUT;
-    const timeout = timeoutRaw ? parseInt(timeoutRaw) : 1e4;
+    const fallbackTimeout = path === "/spawn-session" ? 6e4 : 1e4;
+    const parsedTimeout = timeoutRaw ? Number.parseInt(timeoutRaw, 10) : NaN;
+    const timeout = Number.isFinite(parsedTimeout) ? parsedTimeout : fallbackTimeout;
     const response = await fetch(`http://127.0.0.1:${state.httpPort}${path}`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -4363,6 +4644,7 @@ async function stopDaemon() {
       try {
         await stopDaemonHttp();
         await waitForProcessDeath(state.pid, 2e3);
+        await cleanupDaemonState();
         types.logger.debug("Daemon stopped gracefully via HTTP");
         return;
       } catch (error) {
@@ -4657,37 +4939,6 @@ ${typeLabels[type] || type}:`));
   console.log(chalk.green("\n\u2705 Doctor diagnosis complete!\n"));
 }
 
-function displayQRCode(url) {
-  console.log("=".repeat(80));
-  console.log("\u{1F4F1} To authenticate, scan this QR code with your mobile device:");
-  console.log("=".repeat(80));
-  qrcode.generate(url, { small: true }, (qr) => {
-    for (let l of qr.split("\n")) {
-      console.log(" ".repeat(10) + l);
-    }
-  });
-  console.log("=".repeat(80));
-}
-
-function generateWebAuthUrl(publicKey) {
-  const publicKeyBase64 = types.encodeBase64(publicKey, "base64url");
-  const server = encodeURIComponent(types.configuration.serverUrl);
-  const shouldAutoLogout = (() => {
-    try {
-      const serverUrl = new URL(types.configuration.serverUrl);
-      const webUrl = new URL(types.configuration.webappUrl);
-      const isLoopback = (host) => {
-        const h = String(host || "").toLowerCase();
-        return h === "localhost" || h === "127.0.0.1" || h === "0.0.0.0" || h.endsWith(".localhost");
-      };
-      return isLoopback(serverUrl.hostname) && isLoopback(webUrl.hostname);
-    } catch {
-      return false;
-    }
-  })();
-  return `${types.configuration.webappUrl}/terminal/connect#key=${publicKeyBase64}&server=${server}${shouldAutoLogout ? "&autologout=1" : ""}`;
-}
-
 async function openBrowser(url) {
   try {
     const forceOpen = process.env.FLOCKBAY_FORCE_BROWSER === "1" || process.env.FLOCKBAY_FORCE_BROWSER === "true";
@@ -4705,217 +4956,78 @@ async function openBrowser(url) {
   }
 }
 
-async function doAuth(options) {
-  console.clear();
-  const authMethod = options?.method === "mobile" ? "mobile" : "web";
-  const secret = new Uint8Array(node_crypto.randomBytes(32));
-  const keypair = tweetnacl.box.keyPair.fromSecretKey(secret);
-  try {
-    console.log(`[AUTH DEBUG] Sending auth request to: ${types.configuration.serverUrl}/v1/auth/request`);
-    console.log(`[AUTH DEBUG] Public key: ${types.encodeBase64(keypair.publicKey).substring(0, 20)}...`);
-    await axios.post(`${types.configuration.serverUrl}/v1/auth/request`, {
-      publicKey: types.encodeBase64(keypair.publicKey)
-    });
-    console.log(`[AUTH DEBUG] Auth request sent successfully`);
-  } catch (error) {
-    console.log(`[AUTH DEBUG] Failed to send auth request:`, error);
-    console.log("Failed to create authentication request, please try again later.");
-    return null;
+async function loginWithClerkAndPairMachine() {
+  types.logger.debug("[AUTH] Starting Clerk-based CLI login + machine pairing");
+  const settings = await types.updateSettings(async (s) => {
+    const machineId2 = s.machineId || node_crypto.randomUUID();
+    const serverUrl2 = s.serverUrl || types.configuration.serverUrl;
+    const webappUrl = s.webappUrl || types.configuration.webappUrl;
+    return { ...s, machineId: machineId2, serverUrl: serverUrl2, webappUrl };
+  });
+  const serverUrl = types.configuration.serverUrl.replace(/\/+$/, "");
+  const machineId = String(settings.machineId || "").trim();
+  if (!machineId) {
+    throw new Error("Missing machineId (settings.json).");
   }
-  return authMethod === "mobile" ? await doMobileAuth(keypair) : await doWebAuth(keypair);
-}
-async function doMobileAuth(keypair) {
-  console.clear();
-  console.log("\nMobile Authentication\n");
-  console.log("Scan this QR code with your Flockbay mobile app:\n");
-  const authUrl = "flockbay://terminal?" + types.encodeBase64Url(keypair.publicKey);
-  displayQRCode(authUrl);
-  console.log("\nManual options:");
-  console.log(`- Paste this URL into the Flockbay app: ${authUrl}`);
-  console.log(`- Or open this link in a browser (works well on mobile web): ${generateWebAuthUrl(keypair.publicKey)}`);
-  console.log("");
-  return await waitForAuthentication(keypair);
-}
-async function doWebAuth(keypair) {
-  console.clear();
-  console.log("\nWeb Authentication\n");
-  const webUrl = generateWebAuthUrl(keypair.publicKey);
-  const localWebUrl = (() => {
-    try {
-      const u = new URL(webUrl);
-      u.protocol = "http:";
-      u.hostname = "localhost";
-      u.port = "8081";
-      return u.toString();
-    } catch {
-      return null;
-    }
-  })();
-  const isLocalServer = (() => {
-    try {
-      const server = new URL(types.configuration.serverUrl);
-      const host = server.hostname.toLowerCase();
-      return host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0" || host.endsWith(".localhost");
-    } catch {
-      return false;
-    }
-  })();
-  console.log("Opening your browser...");
-  const primaryUrl = isLocalServer && localWebUrl ? localWebUrl : webUrl;
-  const browserOpened = await openBrowser(primaryUrl);
-  if (browserOpened) {
-    console.log("\u2713 Browser opened\n");
-    console.log("Complete authentication in your browser window.");
-  } else {
-    console.log("Could not open browser automatically.");
-  }
-  console.log("\nIf the browser did not open, please copy and paste this URL:");
-  console.log(webUrl);
-  if (localWebUrl && localWebUrl !== webUrl) {
-    if (isLocalServer) {
-      console.log("\nLocal dev URL (same auth key + server):");
-      console.log(localWebUrl);
-    } else {
-      console.log("\nLocal dev note:");
-      console.log(
-        `- This terminal is waiting on ${types.configuration.serverUrl}, so opening the link on localhost will NOT complete auth.
-- To authenticate locally, re-run with:
-  FLOCKBAY_SERVER_URL=http://localhost:3006 FLOCKBAY_WEBAPP_URL=http://localhost:8081`
-      );
-    }
+  const res = await axios.post(
+    `${serverUrl}/v1/cli/pair/request`,
+    { machineId },
+    { headers: { "Content-Type": "application/json" }, timeout: 3e4 }
+  );
+  const pairingId = String(res?.data?.pairingId || "").trim();
+  const approveUrl = String(res?.data?.approveUrl || "").trim();
+  if (!pairingId || !approveUrl) {
+    throw new Error("Invalid pairing response from server.");
   }
   console.log("");
-  return await waitForAuthentication(keypair);
-}
-async function waitForAuthentication(keypair) {
-  process.stdout.write("Waiting for authentication");
-  let dots = 0;
-  let cancelled = false;
-  const handleInterrupt = () => {
-    cancelled = true;
-    console.log("\n\nAuthentication cancelled.");
-    process.exit(0);
-  };
-  process.on("SIGINT", handleInterrupt);
-  try {
-    while (!cancelled) {
-      try {
-        const response = await axios.post(`${types.configuration.serverUrl}/v1/auth/request`, { publicKey: types.encodeBase64(keypair.publicKey) });
-        if (response.data.state === "authorized") {
-          let token = response.data.token;
-          let r = types.decodeBase64(response.data.response);
-          let decrypted = decryptWithEphemeralKey(r, keypair.secretKey);
-          if (decrypted) {
-            if (decrypted[0] !== 0 || decrypted.length < 33) {
-              console.log("\n\nInvalid auth response (expected V2). Please update your app/CLI.");
-              return null;
-            }
-            const credentials = {
-              publicKey: decrypted.slice(1, 33),
-              machineKey: node_crypto.randomBytes(32),
-              token
-            };
-            await types.writeCredentialsDataKey(credentials);
-            console.log("\n\n\u2713 Authentication successful\n");
-            return {
-              encryption: {
-                type: "dataKey",
-                publicKey: credentials.publicKey,
-                machineKey: credentials.machineKey
-              },
-              token
-            };
-          } else {
-            console.log("\n\nFailed to decrypt response. Please try again.");
-            return null;
-          }
-        }
-      } catch (error) {
-        console.log("\n\nFailed to check authentication status. Please try again.");
-        return null;
+  console.log(chalk.bold("Flockbay CLI login"));
+  console.log(chalk.gray(`Profile: ${types.configuration.profile}`));
+  console.log(chalk.gray(`Server:  ${types.configuration.serverUrl}`));
+  console.log(chalk.gray(`Machine: ${machineId} (${os.hostname()})`));
+  console.log("");
+  console.log("Open this link to sign in with Clerk and approve this machine:");
+  console.log(approveUrl);
+  console.log("");
+  void openBrowser(approveUrl).catch(() => null);
+  const deadline = Date.now() + 10 * 6e4;
+  while (Date.now() < deadline) {
+    await types.delay(1e3);
+    const status = await axios.get(`${serverUrl}/v1/cli/pair/status`, {
+      params: { pairingId, consume: 1 },
+      timeout: 15e3
+    });
+    const state = String(status?.data?.state || "").trim();
+    if (state === "approved") {
+      const machineToken = String(status?.data?.machineToken || "").trim();
+      const orgId = String(status?.data?.orgId || "").trim();
+      if (!machineToken || !orgId) {
+        throw new Error("Pairing approved, but missing token/orgId.");
       }
-      process.stdout.write("\rWaiting for authentication" + ".".repeat(dots % 3 + 1) + "   ");
-      dots++;
-      await types.delay(1e3);
+      const auth = { machineToken, orgId, createdAtMs: Date.now() };
+      await types.writeCredentials(auth);
+      console.log(chalk.green("\u2713 Machine paired to workspace"));
+      console.log(chalk.gray(`Workspace: ${orgId}`));
+      return auth;
+    }
+    if (state === "expired") throw new Error("Pairing expired. Re-run `flockbay login`.");
+    if (state === "consumed") {
+      throw new Error("Pairing token already consumed. If this is unexpected, re-run `flockbay login`.");
     }
-  } finally {
-    process.off("SIGINT", handleInterrupt);
-  }
-  return null;
-}
-function decryptWithEphemeralKey(encryptedBundle, recipientSecretKey) {
-  const ephemeralPublicKey = encryptedBundle.slice(0, 32);
-  const nonce = encryptedBundle.slice(32, 32 + tweetnacl.box.nonceLength);
-  const encrypted = encryptedBundle.slice(32 + tweetnacl.box.nonceLength);
-  const decrypted = tweetnacl.box.open(encrypted, nonce, ephemeralPublicKey, recipientSecretKey);
-  if (!decrypted) {
-    return null;
   }
-  return decrypted;
+  throw new Error("Login timed out. Re-run `flockbay login`.");
 }
-async function authAndSetupMachineIfNeeded(options) {
-  types.logger.debug("[AUTH] Starting auth and machine setup...");
-  const allowAuthFlow = options?.allowAuthFlow !== false;
-  const authMethod = options?.authMethod === "mobile" ? "mobile" : "web";
-  let credentials = await types.readCredentials();
-  if (!credentials) {
-    if (!allowAuthFlow) {
-      throw new Error('Not authenticated. Run "flockbay auth login" first.');
-    }
-    types.logger.debug("[AUTH] No credentials found, starting authentication flow...");
-    const authResult = await doAuth({ method: authMethod });
-    if (!authResult) {
-      throw new Error("Authentication failed or was cancelled");
-    }
-    credentials = authResult;
-  } else {
-    types.logger.debug("[AUTH] Using existing credentials");
+async function ensureMachineAuthOrLogin() {
+  const existing = await types.readCredentials();
+  const settings = await types.readSettings();
+  const machineId = String(settings?.machineId || "").trim();
+  if (existing && existing.machineToken && existing.orgId && machineId) {
+    return { auth: existing, machineId };
   }
-  const canonicalizePath = (p) => String(p || "").trim().replace(/\/+$/, "");
-  const findMatchingExistingMachineId = async () => {
-    try {
-      const res = await axios.get(`${types.configuration.serverUrl}/v1/machines`, {
-        headers: { Authorization: `Bearer ${credentials.token}` }
-      });
-      const machines = Array.isArray(res.data) ? res.data : [];
-      const host = os.hostname();
-      const homeDir = os.homedir();
-      const flockbayHomeDir = canonicalizePath(types.configuration.flockbayHomeDir);
-      const matches = machines.map((m) => {
-        const raw = m?.metadata;
-        let metadata = raw;
-        if (typeof raw === "string") {
-          try {
-            metadata = JSON.parse(raw);
-          } catch {
-            metadata = null;
-          }
-        }
-        return { machine: m, metadata };
-      }).filter(({ machine, metadata }) => {
-        if (!machine?.id || !metadata) return false;
-        if (String(metadata.host || "") !== host) return false;
-        if (String(metadata.homeDir || "") !== homeDir) return false;
-        if (canonicalizePath(String(metadata.flockbayHomeDir || "")) !== flockbayHomeDir) return false;
-        return true;
-      }).map(({ machine }) => machine);
-      if (!matches.length) return null;
-      matches.sort((a, b) => (Number(a.createdAt) || 0) - (Number(b.createdAt) || 0));
-      return String(matches[0].id || "").trim() || null;
-    } catch {
-      return null;
-    }
-  };
-  const existingSettings = await types.readSettings();
-  const preferredMachineId = !existingSettings.machineId ? await findMatchingExistingMachineId() : null;
-  const settings = await types.updateSettings(async (s) => {
-    const machineId = s.machineId || preferredMachineId || node_crypto.randomUUID();
-    const serverUrl = s.serverUrl || types.configuration.serverUrl;
-    const webappUrl = s.webappUrl || types.configuration.webappUrl;
-    return { ...s, machineId, serverUrl, webappUrl };
-  });
-  types.logger.debug(`[AUTH] Machine ID: ${settings.machineId}`);
-  return { credentials, machineId: settings.machineId };
+  const auth = await loginWithClerkAndPairMachine();
+  const updated = await types.readSettings();
+  const mid = String(updated?.machineId || "").trim();
+  if (!mid) throw new Error("Missing machineId after login.");
+  return { auth, machineId: mid };
 }
 
 function resolveTsxImportArgs(projectRoot) {
@@ -4995,6 +5107,7 @@ Error: ${message}` };
 
 function startDaemonControlServer({
   getChildren,
+  getStatus,
   stopSession,
   spawnSession,
   requestShutdown,
@@ -5050,6 +5163,15 @@ function startDaemonControlServer({
         }))
       };
     });
+    typed.post("/status", {
+      schema: {
+        response: {
+          200: z.z.any()
+        }
+      }
+    }, async () => {
+      return getStatus();
+    });
     typed.post("/stop-session", {
       schema: {
         body: z.z.object({
@@ -5189,6 +5311,26 @@ function startDaemonControlServer({
   });
 }
 
+function shouldAutoRestart(params) {
+  const { exit, stopRequested } = params;
+  if (stopRequested) return false;
+  const { code, signal } = exit;
+  const cleanExit = code === 0 && !signal;
+  if (cleanExit) return false;
+  const expectedSignal = signal === "SIGTERM" || signal === "SIGINT";
+  if (expectedSignal) return false;
+  return true;
+}
+function computeNextAutoRestart(params) {
+  const { nowMs, prev, config } = params;
+  const withinWindow = prev && nowMs - prev.firstFailureAtMs <= config.windowMs;
+  const state = withinWindow ? { ...prev } : { attempts: 0, firstFailureAtMs: nowMs };
+  state.attempts += 1;
+  if (state.attempts > config.maxAttempts) return { action: "give_up" };
+  const delayMs = Math.min(config.baseDelayMs * 2 ** (state.attempts - 1), config.maxDelayMs);
+  return { action: "schedule", delayMs, state };
+}
+
 async function pathExists(p) {
   try {
     await fs$2.access(p);
@@ -5259,15 +5401,23 @@ const initialMachineMetadata = {
   flockbayLibDir: types.projectPath()
 };
 async function startDaemon() {
+  let startupCompleted = false;
+  let startupForceExitTimer = null;
   let requestShutdown;
   let resolvesWhenShutdownRequested = new Promise((resolve) => {
     requestShutdown = (source, errorMessage) => {
       types.logger.debug(`[DAEMON RUN] Requesting shutdown (source: ${source}, errorMessage: ${errorMessage})`);
-      setTimeout(async () => {
-        types.logger.debug("[DAEMON RUN] Startup malfunctioned, forcing exit with code 1");
-        await new Promise((resolve2) => setTimeout(resolve2, 100));
-        process.exit(1);
-      }, 1e3);
+      if (!startupCompleted && !startupForceExitTimer) {
+        startupForceExitTimer = setTimeout(async () => {
+          types.logger.debug("[DAEMON RUN] Startup malfunctioned, forcing exit with code 1");
+          await new Promise((resolve2) => setTimeout(resolve2, 100));
+          process.exit(1);
+        }, 1e4);
+        try {
+          startupForceExitTimer.unref();
+        } catch {
+        }
+      }
       resolve({ source, errorMessage });
     };
   });
@@ -5321,7 +5471,7 @@ async function startDaemon() {
     if (caffeinateStarted) {
       types.logger.debug("[DAEMON RUN] Sleep prevention enabled");
     }
-    const { credentials, machineId } = await authAndSetupMachineIfNeeded({ allowAuthFlow: false });
+    const { auth: credentials, machineId } = await ensureMachineAuthOrLogin();
     types.logger.debug("[DAEMON RUN] Auth and machine setup complete");
     const shouldStartUnrealMcp = String(process.env.FLOCKBAY_UNREAL_MCP_ENABLED || "").trim() === "1";
     if (shouldStartUnrealMcp) {
@@ -5334,10 +5484,55 @@ async function startDaemon() {
       }
     }
     const pidToTrackedSession = /* @__PURE__ */ new Map();
+    const stopRequestedSessionIds = /* @__PURE__ */ new Set();
+    const sessionAutoRestart = /* @__PURE__ */ new Map();
+    const autoRestartConfig = {
+      maxAttempts: parseInt(process.env.FLOCKBAY_DAEMON_AUTO_RESTART_MAX_ATTEMPTS || "5", 10),
+      windowMs: parseInt(process.env.FLOCKBAY_DAEMON_AUTO_RESTART_WINDOW_MS || String(10 * 6e4), 10),
+      baseDelayMs: parseInt(process.env.FLOCKBAY_DAEMON_AUTO_RESTART_BASE_DELAY_MS || "1000", 10),
+      maxDelayMs: parseInt(process.env.FLOCKBAY_DAEMON_AUTO_RESTART_MAX_DELAY_MS || "30000", 10)
+    };
     const pidToAwaiter = /* @__PURE__ */ new Map();
     let machineRef = null;
-    let api = null;
+    let apiMachine = null;
     const getCurrentChildren = () => Array.from(pidToTrackedSession.values());
+    const findLatestLogForPid = async (pid) => {
+      const suffix = `-pid-${pid}.log`;
+      try {
+        const files = await fs$1.readdir(types.configuration.logsDir);
+        const matches = files.filter((f) => f.endsWith(suffix));
+        if (matches.length === 0) return null;
+        let best = null;
+        for (const file of matches) {
+          try {
+            const st = await fs$1.stat(path$1.join(types.configuration.logsDir, file));
+            const mtimeMs = Number(st.mtimeMs || 0);
+            if (!best || mtimeMs > best.mtimeMs) best = { file, mtimeMs };
+          } catch {
+          }
+        }
+        return best ? path$1.join(types.configuration.logsDir, best.file) : null;
+      } catch {
+        return null;
+      }
+    };
+    const readLogTail = async (path, maxBytes) => {
+      try {
+        const st = await fs$1.stat(path);
+        const size = Number(st.size || 0);
+        const offset = Math.max(0, size - maxBytes);
+        const handle = await fs$1.open(path, "r");
+        try {
+          const buf = Buffer.alloc(Math.min(maxBytes, size));
+          const { bytesRead } = await handle.read(buf, 0, buf.length, offset);
+          return buf.subarray(0, bytesRead).toString("utf8");
+        } finally {
+          await handle.close();
+        }
+      } catch {
+        return "";
+      }
+    };
     const onSessionWebhook = (sessionId, sessionMetadata) => {
       types.logger.debugLargeJson(`[DAEMON RUN] Session reported`, sessionMetadata);
       const pid = sessionMetadata.hostPid;
@@ -5351,6 +5546,9 @@ async function startDaemon() {
       if (existingSession && existingSession.startedBy === "daemon") {
         existingSession.serverSessionId = sessionId;
         existingSession.serverSessionMetadataFromLocalWebhook = sessionMetadata;
+        if (existingSession.spawnOptions) {
+          existingSession.spawnOptions = { ...existingSession.spawnOptions, sessionId };
+        }
         types.logger.debug(`[DAEMON RUN] Updated daemon-spawned session ${sessionId} with metadata`);
         const awaiter = pidToAwaiter.get(pid);
         if (awaiter) {
@@ -5389,16 +5587,7 @@ async function startDaemon() {
       const refreshBypassFromServerIfNeeded = async () => {
         if (bypassUeGates) return;
         if (envBypassUeGates) return;
-        if (!api) return;
-        const targetMachineId = requestedMachineId || machineRef?.id;
-        if (!targetMachineId) return;
-        try {
-          const latest = await api.getMachine(targetMachineId);
-          machineRef = latest;
-          bypassUeGates = envBypassUeGates || Boolean(latest?.metadata?.flockbayDevBypassUeGates);
-        } catch (err) {
-          bypassRefreshError = err instanceof Error ? err.message : String(err);
-        }
+        bypassRefreshError = "refresh_not_supported";
       };
       const detection = await detectUnrealProject(directory);
       if (!detection.ok && !bypassUeGates) {
@@ -5419,7 +5608,7 @@ async function startDaemon() {
         const res = await fetch(url, {
           method: "POST",
           headers: {
-            Authorization: `Bearer ${credentials.token}`,
+            Authorization: `Machine ${credentials.machineToken}`,
             "Content-Type": "application/json"
           },
           body: JSON.stringify(body ?? {})
@@ -5620,11 +5809,16 @@ Fix: restart session creation and re-select the project.`
         }
         const args = [
           agentCommand,
+          "--profile",
+          types.configuration.profile,
           "--flockbay-starting-mode",
           "remote",
           "--started-by",
           "daemon"
         ];
+        if (options.sessionId) {
+          args.push("--flockbay-session-id", String(options.sessionId));
+        }
         const captureChildOutput = Boolean(process.env.DEBUG);
         const spawnEnv = {
           ...process.env,
@@ -5667,24 +5861,30 @@ Fix: restart session creation and re-select the project.`
           };
         }
         types.logger.debug(`[DAEMON RUN] Spawned process with PID ${sessionProcess.pid}`);
+        const spawnOptionsForTracking = {
+          ...options,
+          approvedNewDirectoryCreation: true,
+          coordination: coordinationForSpawn && typeof coordinationForSpawn === "object" ? coordinationForSpawn : options.coordination ?? null
+        };
         const trackedSession = {
           startedBy: "daemon",
           pid: sessionProcess.pid,
           childProcess: sessionProcess,
           directoryCreated,
+          spawnOptions: spawnOptionsForTracking,
           message: directoryCreated ? `The path '${directory}' did not exist. We created a new folder and spawned a new session there.` : void 0
         };
         pidToTrackedSession.set(sessionProcess.pid, trackedSession);
         sessionProcess.on("exit", (code, signal) => {
           types.logger.debug(`[DAEMON RUN] Child PID ${sessionProcess.pid} exited with code ${code}, signal ${signal}`);
           if (sessionProcess.pid) {
-            onChildExited(sessionProcess.pid);
+            onChildExited(sessionProcess.pid, { code, signal });
           }
         });
         sessionProcess.on("error", (error) => {
           types.logger.debug(`[DAEMON RUN] Child process error:`, error);
           if (sessionProcess.pid) {
-            onChildExited(sessionProcess.pid);
+            onChildExited(sessionProcess.pid, { code: null, signal: null });
           }
         });
         types.logger.debug(`[DAEMON RUN] Waiting for session webhook for PID ${sessionProcess.pid}`);
@@ -5707,17 +5907,25 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
           }, 3e4);
           const onEarlyExit = (code, signal) => {
             clearTimeout(timeout);
-            settleOnce({
-              type: "error",
-              errorMessage: `Session process exited before webhook (PID ${pid}, code ${code ?? "unknown"}, signal ${signal ?? "none"})`
-            });
+            void (async () => {
+              const logPath = await findLatestLogForPid(pid);
+              settleOnce({
+                type: "error",
+                errorMessage: `Session process exited before webhook (PID ${pid}, code ${code ?? "unknown"}, signal ${signal ?? "none"}).
+Log: ${logPath || `not found (check ${types.configuration.logsDir})`}`
+              });
+            })();
           };
           const onEarlyError = (error) => {
             clearTimeout(timeout);
-            settleOnce({
-              type: "error",
-              errorMessage: `Session process error before webhook (PID ${pid}): ${error.message}`
-            });
+            void (async () => {
+              const logPath = await findLatestLogForPid(pid);
+              settleOnce({
+                type: "error",
+                errorMessage: `Session process error before webhook (PID ${pid}): ${error.message}.
+Log: ${logPath || `not found (check ${types.configuration.logsDir})`}`
+              });
+            })();
           };
           sessionProcess.once("exit", onEarlyExit);
           sessionProcess.once("error", onEarlyError);
@@ -5767,8 +5975,13 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
     };
     const stopSession = (sessionId) => {
       types.logger.debug(`[DAEMON RUN] Attempting to stop session ${sessionId}`);
+      if (sessionId && !sessionId.startsWith("PID-")) {
+        stopRequestedSessionIds.add(sessionId);
+      }
       for (const [pid, session] of pidToTrackedSession.entries()) {
         if (session.serverSessionId === sessionId || sessionId.startsWith("PID-") && pid === parseInt(sessionId.replace("PID-", ""))) {
+          session.stopRequested = true;
+          if (session.serverSessionId) stopRequestedSessionIds.add(session.serverSessionId);
           if (session.startedBy === "daemon" && session.childProcess) {
             try {
               session.childProcess.kill("SIGTERM");
@@ -5784,20 +5997,144 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
               types.logger.debug(`[DAEMON RUN] Failed to kill external session PID ${pid}:`, error);
             }
           }
-          pidToTrackedSession.delete(pid);
-          types.logger.debug(`[DAEMON RUN] Removed session ${sessionId} from tracking`);
+          types.logger.debug(`[DAEMON RUN] Stop requested for session ${sessionId}; waiting for exit to remove tracking`);
           return true;
         }
       }
       types.logger.debug(`[DAEMON RUN] Session ${sessionId} not found`);
       return false;
     };
-    const onChildExited = (pid) => {
+    const scheduleAutoRestart = (params) => {
+      const { sessionId, spawnOptions, reason } = params;
+      if (stopRequestedSessionIds.has(sessionId)) {
+        types.logger.debug(`[DAEMON RUN] Auto-restart suppressed (stop requested) for session ${sessionId}`);
+        return;
+      }
+      const now = Date.now();
+      const existing = sessionAutoRestart.get(sessionId);
+      if (existing?.timer) {
+        types.logger.debug(`[DAEMON RUN] Auto-restart already scheduled for session ${sessionId}`);
+        return;
+      }
+      const next = computeNextAutoRestart({
+        nowMs: now,
+        prev: existing?.state ?? null,
+        config: autoRestartConfig
+      });
+      if (next.action === "give_up") {
+        types.logger.debug(
+          `[DAEMON RUN] Auto-restart giving up for session ${sessionId} after ${autoRestartConfig.maxAttempts} attempt(s) within ${autoRestartConfig.windowMs}ms (last reason: ${reason})`
+        );
+        sessionAutoRestart.delete(sessionId);
+        return;
+      }
+      const delay = next.delayMs;
+      types.logger.debug(
+        `[DAEMON RUN] Auto-restarting session ${sessionId} in ${delay}ms (attempt ${next.state.attempts}/${autoRestartConfig.maxAttempts}, reason: ${reason})`
+      );
+      const entry = { state: next.state, timer: void 0 };
+      entry.timer = setTimeout(() => {
+        entry.timer = void 0;
+        sessionAutoRestart.set(sessionId, entry);
+        if (stopRequestedSessionIds.has(sessionId)) {
+          types.logger.debug(`[DAEMON RUN] Auto-restart canceled (stop requested) for session ${sessionId}`);
+          return;
+        }
+        void (async () => {
+          try {
+            const result = await spawnSession({
+              ...spawnOptions,
+              approvedNewDirectoryCreation: true,
+              sessionId
+            });
+            if (result.type === "success") {
+              types.logger.debug(`[DAEMON RUN] Auto-restart succeeded for session ${sessionId}`);
+              sessionAutoRestart.delete(sessionId);
+              return;
+            }
+            types.logger.debug(
+              `[DAEMON RUN] Auto-restart failed for session ${sessionId} (type=${result.type}): ${result.type === "error" ? result.errorMessage : "needs-user-approval"}`
+            );
+          } catch (err) {
+            types.logger.debug(`[DAEMON RUN] Auto-restart threw for session ${sessionId}:`, err);
+          }
+          scheduleAutoRestart({ sessionId, spawnOptions, reason: "restart_failed" });
+        })();
+      }, delay);
+      try {
+        entry.timer.unref();
+      } catch {
+      }
+      sessionAutoRestart.set(sessionId, entry);
+    };
+    const onChildExited = (pid, exit) => {
+      const tracked = pidToTrackedSession.get(pid);
       types.logger.debug(`[DAEMON RUN] Removing exited process PID ${pid} from tracking`);
       pidToTrackedSession.delete(pid);
+      if (!tracked) return;
+      tracked.lastExit = {
+        code: exit?.code ?? null,
+        signal: exit?.signal ?? null,
+        atMs: Date.now()
+      };
+      const sessionId = String(tracked.serverSessionId || "").trim();
+      if (!sessionId) return;
+      if (tracked.stopRequested || stopRequestedSessionIds.has(sessionId)) {
+        types.logger.debug(`[DAEMON RUN] Not auto-restarting session ${sessionId} (stop requested)`);
+        sessionAutoRestart.delete(sessionId);
+        return;
+      }
+      const code = tracked.lastExit.code;
+      const signal = tracked.lastExit.signal;
+      if (!shouldAutoRestart({
+        exit: { code, signal },
+        stopRequested: Boolean(tracked.stopRequested || stopRequestedSessionIds.has(sessionId))
+      })) {
+        types.logger.debug(`[DAEMON RUN] Not auto-restarting session ${sessionId} (clean exit)`);
+        sessionAutoRestart.delete(sessionId);
+        return;
+      }
+      if (!tracked.spawnOptions) {
+        types.logger.debug(`[DAEMON RUN] Not auto-restarting session ${sessionId} (missing spawn options)`);
+        return;
+      }
+      void (async () => {
+        const logPath = await findLatestLogForPid(pid);
+        if (!logPath) return;
+        const tail = await readLogTail(logPath, 16384);
+        if (!tail.trim()) return;
+        types.logger.debug(
+          `[DAEMON RUN] Session runtime log tail for ${sessionId} (pid=${pid}, log=${path$1.basename(logPath)}):
+` + tail
+        );
+      })();
+      scheduleAutoRestart({
+        sessionId,
+        spawnOptions: tracked.spawnOptions,
+        reason: `exit(code=${code ?? "null"},signal=${signal ?? "null"})`
+      });
     };
     const { port: controlPort, stop } = await startDaemonControlServer({
       getChildren: getCurrentChildren,
+      getStatus: () => ({
+        profile: types.configuration.profile,
+        serverUrl: types.configuration.serverUrl,
+        webappUrl: types.configuration.webappUrl,
+        orgId: credentials?.orgId || null,
+        machineId,
+        daemonPid: process.pid,
+        daemonHttpPort: controlPort,
+        startedWithCliVersion: types.packageJson.version,
+        machine: machineRef ? { id: machineRef.id, seq: machineRef.seq || 0 } : null,
+        connection: apiMachine ? apiMachine.getStatusSnapshot() : {
+          connected: false,
+          lastConnectError: null,
+          lastDisconnectReason: null,
+          lastHttpUpsertError: null,
+          lastHttpUpsertStatus: null,
+          lastHttpUpsertAt: null
+        }
+      }),
       stopSession,
       spawnSession,
       requestShutdown: () => requestShutdown("flockbay-cli"),
@@ -5819,93 +6156,89 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
       httpPort: controlPort,
       startedAt: Date.now()
     };
-    const apiClient = await types.ApiClient.create(credentials);
-    api = apiClient;
-    let machine;
-    try {
-      const existing = await apiClient.getMachine(machineId);
-      machine = await apiClient.getOrCreateMachine({
-        machineId,
-        metadata: { ...existing.metadata || {}, ...initialMachineMetadata },
-        daemonState: initialDaemonState
-      });
-    } catch (error) {
-      const status = error?.response?.status;
-      if (status === 404) {
-        machine = await apiClient.getOrCreateMachine({
-          machineId,
-          metadata: initialMachineMetadata,
-          daemonState: initialDaemonState
-        });
-      } else {
-        throw error;
-      }
-    }
-    types.logger.debug(`[DAEMON RUN] Machine registered: ${machine.id}`);
+    const machine = {
+      id: machineId,
+      seq: 0,
+      active: false,
+      activeAt: null,
+      createdAt: null,
+      updatedAt: null,
+      metadata: { ...initialMachineMetadata },
+      daemonState: initialDaemonState
+    };
     machineRef = machine;
-    const apiMachine = apiClient.machineSyncClient(machine);
+    apiMachine = new types.ApiMachineClient(credentials.machineToken, machine);
     apiMachine.setRPCHandlers({
       spawnSession,
       stopSession,
       requestShutdown: () => requestShutdown("flockbay-app")
     });
-    apiMachine.connect();
+    try {
+      apiMachine.connect();
+    } catch (err) {
+      types.logger.debug("[DAEMON RUN] Failed to connect machine socket (will remain offline until restart):", err);
+    }
     const heartbeatIntervalMs = parseInt(process.env.FLOCKBAY_DAEMON_HEARTBEAT_INTERVAL || "60000");
     let heartbeatRunning = false;
     const restartOnStaleVersionAndHeartbeat = setInterval(async () => {
-      if (heartbeatRunning) {
-        return;
-      }
+      if (heartbeatRunning) return;
       heartbeatRunning = true;
-      if (process.env.DEBUG) {
-        types.logger.debug(`[DAEMON RUN] Health check started at ${(/* @__PURE__ */ new Date()).toLocaleString()}`);
-      }
-      for (const [pid, _] of pidToTrackedSession.entries()) {
+      try {
+        if (process.env.DEBUG) {
+          types.logger.debug(`[DAEMON RUN] Health check started at ${(/* @__PURE__ */ new Date()).toLocaleString()}`);
+        }
+        for (const [pid, _] of pidToTrackedSession.entries()) {
+          try {
+            process.kill(pid, 0);
+          } catch (error) {
+            types.logger.debug(`[DAEMON RUN] Removing stale session with PID ${pid} (process no longer exists)`);
+            pidToTrackedSession.delete(pid);
+          }
+        }
         try {
-          process.kill(pid, 0);
+          const projectVersion = JSON.parse(fs$3.readFileSync(path$1.join(types.projectPath(), "package.json"), "utf-8")).version;
+          if (projectVersion !== types.configuration.currentCliVersion) {
+            types.logger.debug("[DAEMON RUN] Daemon is outdated, triggering self-restart with latest version, clearing heartbeat interval");
+            clearInterval(restartOnStaleVersionAndHeartbeat);
+            try {
+              spawnFlockbayCLI(["daemon", "start"], {
+                detached: true,
+                stdio: "ignore"
+              });
+            } catch (error) {
+              types.logger.debug("[DAEMON RUN] Failed to spawn new daemon, this can happen during integration tests", error);
+            }
+            types.logger.debug("[DAEMON RUN] Hanging briefly - waiting for CLI to kill us due to stale version");
+            await new Promise((resolve) => setTimeout(resolve, 1e4));
+            process.exit(0);
+          }
         } catch (error) {
-          types.logger.debug(`[DAEMON RUN] Removing stale session with PID ${pid} (process no longer exists)`);
-          pidToTrackedSession.delete(pid);
+          types.logger.debug("[DAEMON RUN] Failed to check CLI version during health check", error);
+        }
+        const daemonState = await types.readDaemonState();
+        if (daemonState && daemonState.pid !== process.pid) {
+          types.logger.debug("[DAEMON RUN] Somehow a different daemon was started without killing us. We should kill ourselves.");
+          requestShutdown("exception", "A different daemon was started without killing us. We should kill ourselves.");
         }
-      }
-      const projectVersion = JSON.parse(fs$3.readFileSync(path$1.join(types.projectPath(), "package.json"), "utf-8")).version;
-      if (projectVersion !== types.configuration.currentCliVersion) {
-        types.logger.debug("[DAEMON RUN] Daemon is outdated, triggering self-restart with latest version, clearing heartbeat interval");
-        clearInterval(restartOnStaleVersionAndHeartbeat);
         try {
-          spawnFlockbayCLI(["daemon", "start"], {
-            detached: true,
-            stdio: "ignore"
-          });
+          const updatedState = {
+            pid: process.pid,
+            httpPort: controlPort,
+            startTime: fileState.startTime,
+            startedWithCliVersion: types.packageJson.version,
+            lastHeartbeat: (/* @__PURE__ */ new Date()).toLocaleString(),
+            daemonLogPath: fileState.daemonLogPath
+          };
+          types.writeDaemonState(updatedState);
+          if (process.env.DEBUG) {
+            types.logger.debug(`[DAEMON RUN] Health check completed at ${updatedState.lastHeartbeat}`);
+          }
         } catch (error) {
-          types.logger.debug("[DAEMON RUN] Failed to spawn new daemon, this is quite likely to happen during integration tests as we are cleaning out dist/ directory", error);
-        }
-        types.logger.debug("[DAEMON RUN] Hanging for a bit - waiting for CLI to kill us because we are running outdated version of the code");
-        await new Promise((resolve) => setTimeout(resolve, 1e4));
-        process.exit(0);
-      }
-      const daemonState = await types.readDaemonState();
-      if (daemonState && daemonState.pid !== process.pid) {
-        types.logger.debug("[DAEMON RUN] Somehow a different daemon was started without killing us. We should kill ourselves.");
-        requestShutdown("exception", "A different daemon was started without killing us. We should kill ourselves.");
-      }
-      try {
-        const updatedState = {
-          pid: process.pid,
-          httpPort: controlPort,
-          startTime: fileState.startTime,
-          startedWithCliVersion: types.packageJson.version,
-          lastHeartbeat: (/* @__PURE__ */ new Date()).toLocaleString(),
-          daemonLogPath: fileState.daemonLogPath
-        };
-        types.writeDaemonState(updatedState);
-        if (process.env.DEBUG) {
-          types.logger.debug(`[DAEMON RUN] Health check completed at ${updatedState.lastHeartbeat}`);
+          types.logger.debug("[DAEMON RUN] Failed to write heartbeat", error);
         }
-      } catch (error) {
-        types.logger.debug("[DAEMON RUN] Failed to write heartbeat", error);
+      } finally {
+        heartbeatRunning = false;
       }
-      heartbeatRunning = false;
     }, heartbeatIntervalMs);
     const cleanupAndShutdown = async (source, errorMessage) => {
       types.logger.debug(`[DAEMON RUN] Starting proper cleanup (source: ${source}, errorMessage: ${errorMessage})...`);
@@ -5914,13 +6247,15 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
         clearInterval(restartOnStaleVersionAndHeartbeat);
         types.logger.debug("[DAEMON RUN] Health check interval cleared");
       }
-      await apiMachine.updateDaemonState((state) => ({
-        ...state,
-        status: "shutting-down",
-        shutdownRequestedAt: Date.now(),
-        shutdownSource: source
-      }));
-      await new Promise((resolve) => setTimeout(resolve, 100));
+      try {
+        await apiMachine?.updateDaemonStateOnce?.((state) => ({
+          ...state,
+          status: "shutting-down",
+          shutdownRequestedAt: Date.now(),
+          shutdownSource: source
+        }));
+      } catch {
+      }
       if (killSessionsOnShutdown) {
         try {
           const tracked = Array.from(pidToTrackedSession.entries());
@@ -5971,7 +6306,7 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
       } else {
         types.logger.debug("[DAEMON RUN] Preserving session processes across daemon shutdown");
       }
-      apiMachine.shutdown();
+      apiMachine?.shutdown();
       try {
         unrealMcpChild?.kill();
       } catch {
@@ -5986,7 +6321,12 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
       process.exit(0);
     };
     types.logger.debug("[DAEMON RUN] Daemon started successfully, waiting for shutdown request");
+    startupCompleted = true;
     const shutdownRequest = await resolvesWhenShutdownRequested;
+    if (startupForceExitTimer) {
+      clearTimeout(startupForceExitTimer);
+      startupForceExitTimer = null;
+    }
     await cleanupAndShutdown(shutdownRequest.source, shutdownRequest.errorMessage);
   } catch (error) {
     types.logger.debug("[DAEMON RUN][FATAL] Failed somewhere unexpectedly - exiting with code 1", error);
@@ -6029,12 +6369,259 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
 async function runMechanicRun(_input) {
   return {
     ok: false,
-    errorMessage: "Mechanic runs are disabled (legacy Unreal project plugin removed).",
+    errorMessage: "Mechanic runs are disabled.",
     hint: "Remove reliance on `unreal_mechanic_run`, or re-introduce this tool as a future feature built on project-local tooling.",
     artifactsDir: null
   };
 }
 
+function targetPlatform() {
+  if (process.platform === "win32") return "Win64";
+  if (process.platform === "darwin") return "Mac";
+  return "Linux";
+}
+function buildScriptPath(engineRoot) {
+  if (process.platform === "win32") {
+    return path.join(engineRoot, "Engine", "Build", "BatchFiles", "Build.bat");
+  }
+  return path.join(engineRoot, "Engine", "Build", "BatchFiles", "Build.sh");
+}
+function parseBuildIssuesFromText(text, limit) {
+  const issues = [];
+  let errors = 0;
+  let warnings = 0;
+  let truncated = false;
+  const clangRe = /^(.+?):(\d+):(\d+):\s+(warning|error):\s+(.*)$/;
+  const msvcRe = /^(.+?)\((\d+)\):\s+(warning|error)\s+([A-Z]+\d+):\s+(.*)$/;
+  const lines = String(text ?? "").split(/\r?\n/);
+  for (const line of lines) {
+    let m = clangRe.exec(line);
+    if (m) {
+      const severity = m[4] === "warning" ? "warning" : "error";
+      if (severity === "error") errors += 1;
+      else warnings += 1;
+      if (issues.length < limit) {
+        issues.push({
+          file: m[1] ? String(m[1]) : null,
+          line: Number(m[2]) || null,
+          column: Number(m[3]) || null,
+          severity,
+          code: null,
+          message: String(m[5] ?? "").trim()
+        });
+      } else {
+        truncated = true;
+      }
+      continue;
+    }
+    m = msvcRe.exec(line);
+    if (m) {
+      const severity = m[3] === "warning" ? "warning" : "error";
+      if (severity === "error") errors += 1;
+      else warnings += 1;
+      if (issues.length < limit) {
+        issues.push({
+          file: m[1] ? String(m[1]) : null,
+          line: Number(m[2]) || null,
+          column: null,
+          severity,
+          code: m[4] ? String(m[4]) : null,
+          message: String(m[5] ?? "").trim()
+        });
+      } else {
+        truncated = true;
+      }
+      continue;
+    }
+  }
+  return { issues, errors, warnings, truncated };
+}
+async function buildUnrealProject(args) {
+  const uprojectPath = args.uprojectPath;
+  const engineRoot = args.engineRoot;
+  const configuration = args.configuration ?? "Development";
+  const target = args.target ?? "Editor";
+  const timeoutMs = Math.max(3e4, args.timeoutMs ?? 20 * 6e4);
+  const issuesLimit = Math.max(1, Math.min(2e3, args.issuesLimit ?? 250));
+  if (!uprojectPath || !path.isAbsolute(uprojectPath) || !uprojectPath.toLowerCase().endsWith(".uproject")) {
+    return {
+      ok: false,
+      exitCode: null,
+      logPath: "",
+      issues: [],
+      errors: 0,
+      warnings: 0,
+      truncated: false,
+      errorMessage: `Invalid uprojectPath (must be an absolute path to *.uproject): ${String(uprojectPath)}`
+    };
+  }
+  if (!fs.existsSync(uprojectPath)) {
+    return {
+      ok: false,
+      exitCode: null,
+      logPath: "",
+      issues: [],
+      errors: 0,
+      warnings: 0,
+      truncated: false,
+      errorMessage: `uprojectPath not found: ${uprojectPath}`
+    };
+  }
+  const script = buildScriptPath(engineRoot);
+  if (!fs.existsSync(script)) {
+    return {
+      ok: false,
+      exitCode: null,
+      logPath: "",
+      issues: [],
+      errors: 0,
+      warnings: 0,
+      truncated: false,
+      errorMessage: `Missing Unreal build script: ${script}`
+    };
+  }
+  const projectName = path.basename(uprojectPath).replace(/\.uproject$/i, "");
+  const targetName = target === "Editor" ? `${projectName}Editor` : projectName;
+  const platform = targetPlatform();
+  const logDir = args.logDir ?? path.join(path.dirname(uprojectPath), "Saved", "Logs", "Flockbay");
+  fs.mkdirSync(logDir, { recursive: true });
+  const logPath = path.join(logDir, `flockbay_build_${Date.now()}.log`);
+  const buildArgs = [
+    targetName,
+    platform,
+    configuration,
+    `-Project=${uprojectPath}`,
+    "-WaitMutex",
+    "-NoHotReload"
+  ];
+  const logStream = fs.createWriteStream(logPath, { flags: "a" });
+  logStream.write(`engineRoot: ${engineRoot}
+`);
+  logStream.write(`uprojectPath: ${uprojectPath}
+`);
+  logStream.write(`script: ${script}
+`);
+  logStream.write(`args: ${JSON.stringify(buildArgs)}
+
+`);
+  const child = process.platform === "win32" ? node_child_process.spawn("cmd.exe", ["/c", script, ...buildArgs], { stdio: ["ignore", "pipe", "pipe"] }) : node_child_process.spawn(script, buildArgs, { stdio: ["ignore", "pipe", "pipe"] });
+  let combinedTail = "";
+  const appendTail = (chunk) => {
+    combinedTail += chunk.toString("utf8");
+    if (combinedTail.length > 2e6) combinedTail = combinedTail.slice(-4e5);
+  };
+  child.stdout?.on("data", (chunk) => {
+    logStream.write(chunk);
+    appendTail(chunk);
+  });
+  child.stderr?.on("data", (chunk) => {
+    logStream.write(chunk);
+    appendTail(chunk);
+  });
+  const exitCode = await new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+      resolve(null);
+    }, timeoutMs);
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve(code);
+    });
+    child.on("error", () => {
+      clearTimeout(timer);
+      resolve(null);
+    });
+  });
+  logStream.end(`
+exitCode: ${exitCode}
+`);
+  const parsed = parseBuildIssuesFromText(combinedTail, issuesLimit);
+  const ok = exitCode === 0;
+  if (!ok) {
+    return {
+      ok: false,
+      exitCode,
+      logPath,
+      ...parsed,
+      errorMessage: exitCode === null ? `Build timed out after ${timeoutMs}ms. Log: ${logPath}` : `Build failed (exitCode=${exitCode}). Log: ${logPath}`
+    };
+  }
+  return {
+    ok: true,
+    exitCode: exitCode ?? 0,
+    logPath,
+    ...parsed
+  };
+}
+
+function stampForFilename() {
+  const d = /* @__PURE__ */ new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  const yyyy = d.getFullYear();
+  const mm = pad(d.getMonth() + 1);
+  const dd = pad(d.getDate());
+  const hh = pad(d.getHours());
+  const mi = pad(d.getMinutes());
+  const ss = pad(d.getSeconds());
+  return `${yyyy}${mm}${dd}-${hh}${mi}${ss}`;
+}
+async function runUnrealSmokeTest(args) {
+  const startedAtMs = Date.now();
+  const timeoutMs = Math.max(5e3, args.timeoutMs ?? 3e4);
+  const stabilizeMs = Math.max(250, args.stabilizeMs ?? 1500);
+  const stopIfPlaying = args.stopIfPlaying ?? true;
+  const screenshotDir = path.join(path.dirname(args.uprojectPath), "Saved", "Screenshots", "Flockbay");
+  await fs$2.mkdir(screenshotDir, { recursive: true });
+  const screenshotPath = path.join(screenshotDir, `Flockbay_smoke_test_${stampForFilename()}.png`);
+  let started = false;
+  let stopped = false;
+  try {
+    const status = await types.sendUnrealMcpTcpCommand({ type: "get_play_in_editor_status", params: {}, timeoutMs: Math.min(timeoutMs, 5e3) });
+    const result = status?.result && typeof status.result === "object" ? status.result : status;
+    const isPlaying = typeof result?.isPlaying === "boolean" ? result.isPlaying : null;
+    if (isPlaying) {
+      if (!stopIfPlaying) {
+        return {
+          ok: false,
+          durationMs: Date.now() - startedAtMs,
+          started: false,
+          stopped: false,
+          screenshotPath: null,
+          errorMessage: "PIE is currently running. Stop PIE first or re-run with stopIfPlaying=true."
+        };
+      }
+      await types.sendUnrealMcpTcpCommand({ type: "stop_play_in_editor", params: {}, timeoutMs: Math.min(timeoutMs, 1e4) });
+    }
+    const playRes = await types.sendUnrealMcpTcpCommand({ type: "play_in_editor_windowed", params: {}, timeoutMs: Math.min(timeoutMs, 1e4) });
+    const playResult = playRes?.result && typeof playRes.result === "object" ? playRes.result : playRes;
+    started = typeof playResult?.started === "boolean" ? playResult.started : true;
+    await new Promise((r) => setTimeout(r, stabilizeMs));
+    await types.sendUnrealMcpTcpCommand({ type: "take_screenshot", params: { filepath: screenshotPath }, timeoutMs: Math.min(timeoutMs, 2e4) });
+    await types.sendUnrealMcpTcpCommand({ type: "stop_play_in_editor", params: {}, timeoutMs: Math.min(timeoutMs, 1e4) });
+    stopped = true;
+    return {
+      ok: true,
+      durationMs: Date.now() - startedAtMs,
+      started,
+      stopped,
+      screenshotPath
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      durationMs: Date.now() - startedAtMs,
+      started,
+      stopped,
+      screenshotPath: screenshotPath || null,
+      errorMessage: message
+    };
+  }
+}
+
 function safeJsonParse(value) {
   try {
     return JSON.parse(value);
@@ -6251,12 +6838,172 @@ class ElicitationHub {
   }
 }
 
+function encodeBase64(buffer, variant = "base64") {
+  if (variant === "base64url") {
+    return encodeBase64Url(buffer);
+  }
+  return Buffer.from(buffer).toString("base64");
+}
+function encodeBase64Url(buffer) {
+  return Buffer.from(buffer).toString("base64").replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+function getRandomBytes(size) {
+  return new Uint8Array(node_crypto.randomBytes(size));
+}
+function encryptWithDataKey(data, dataKey) {
+  const nonce = getRandomBytes(12);
+  const cipher = node_crypto.createCipheriv("aes-256-gcm", dataKey, nonce);
+  const plaintext = new TextEncoder().encode(JSON.stringify(data));
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext),
+    cipher.final()
+  ]);
+  const authTag = cipher.getAuthTag();
+  const bundle = new Uint8Array(12 + encrypted.length + 16 + 1);
+  bundle.set([0], 0);
+  bundle.set(nonce, 1);
+  bundle.set(new Uint8Array(encrypted), 13);
+  bundle.set(new Uint8Array(authTag), 13 + encrypted.length);
+  return bundle;
+}
+function encrypt(key, data) {
+  return encryptWithDataKey(data, key);
+}
+
 function deriveScreenshotViewIdFromFilename(name) {
   const base = name.replace(/\.[^.]+$/, "");
   const prefixed = /^Flockbay_(.+)$/.exec(base);
   const raw = (prefixed ? prefixed[1] : base).trim();
   return raw.replace(/_\d{8}-\d{6}$/, "").trim() || base;
 }
+async function readJsonFile(filePath) {
+  const raw = await fs$2.readFile(filePath, "utf8");
+  return JSON.parse(raw);
+}
+function parseMajorMinorOrNull(raw) {
+  if (typeof raw !== "string") return null;
+  const m = raw.trim().match(/(\d+)\.(\d+)/);
+  if (!m) return null;
+  const major = Number(m[1]);
+  const minor = Number(m[2]);
+  if (!Number.isFinite(major) || !Number.isFinite(minor)) return null;
+  return { major, minor };
+}
+async function readUprojectEngineAssociationOrNull(uprojectPath) {
+  try {
+    const json = await readJsonFile(uprojectPath);
+    return parseMajorMinorOrNull(json?.EngineAssociation);
+  } catch {
+    return null;
+  }
+}
+function isValidEngineRoot(engineRoot) {
+  if (!engineRoot) return false;
+  if (!fs.existsSync(engineRoot)) return false;
+  if (!fs.existsSync(path.join(engineRoot, "Engine"))) return false;
+  const buildVersion = path.join(engineRoot, "Engine", "Build", "Build.version");
+  if (fs.existsSync(buildVersion)) return true;
+  const editorCmd = process.platform === "darwin" ? path.join(engineRoot, "Engine", "Binaries", "Mac", "UnrealEditor-Cmd") : process.platform === "win32" ? path.join(engineRoot, "Engine", "Binaries", "Win64", "UnrealEditor-Cmd.exe") : process.platform === "linux" ? path.join(engineRoot, "Engine", "Binaries", "Linux", "UnrealEditor-Cmd") : "";
+  if (editorCmd && fs.existsSync(editorCmd)) return true;
+  return false;
+}
+function engineRootCandidatesForVersion(platform, version) {
+  const suffix = `${version.major}.${version.minor}`;
+  if (platform === "darwin") {
+    return [
+      `/Users/Shared/Epic Games/UE_${suffix}`,
+      `/Applications/Epic Games/UE_${suffix}`,
+      `/Applications/Unreal Engine/UE_${suffix}`
+    ];
+  }
+  if (platform === "win32") {
+    return [
+      `C:\\\\Program Files\\\\Epic Games\\\\UE_${suffix}`
+    ];
+  }
+  return [];
+}
+async function readEngineRootMajorMinorOrNull(engineRoot) {
+  const buildVersionPath = path.join(engineRoot, "Engine", "Build", "Build.version");
+  try {
+    if (fs.existsSync(buildVersionPath)) {
+      const json = await readJsonFile(buildVersionPath);
+      const major2 = Number(json?.MajorVersion);
+      const minor2 = Number(json?.MinorVersion);
+      if (Number.isFinite(major2) && Number.isFinite(minor2)) return { major: major2, minor: minor2 };
+    }
+  } catch {
+  }
+  const m = engineRoot.match(/UE_(\d+)\.(\d+)/);
+  if (!m) return null;
+  const major = Number(m[1]);
+  const minor = Number(m[2]);
+  if (!Number.isFinite(major) || !Number.isFinite(minor)) return null;
+  return { major, minor };
+}
+async function assertEngineRootMatchesUprojectOrThrow(args) {
+  const engineAssociation = await readUprojectEngineAssociationOrNull(args.uprojectPath);
+  if (!engineAssociation) return;
+  const engineRootVersion = await readEngineRootMajorMinorOrNull(args.engineRoot);
+  if (!engineRootVersion) return;
+  if (engineRootVersion.major !== engineAssociation.major || engineRootVersion.minor !== engineAssociation.minor) {
+    const candidates = engineRootCandidatesForVersion(process.platform, engineAssociation);
+    const suggestedEngineRoot = candidates.find((c) => isValidEngineRoot(c)) || candidates[0] || null;
+    throw new Error(
+      [
+        `Engine mismatch: this project targets UE ${engineAssociation.major}.${engineAssociation.minor} (EngineAssociation),`,
+        `but the provided engineRoot is UE ${engineRootVersion.major}.${engineRootVersion.minor}: ${args.engineRoot}`,
+        "",
+        args.source === "env" ? `Fix: update ENGINE_ROOT to a matching UE install (or unset it and let the tool infer from the .uproject).` : `Fix: pass a matching engineRoot (or omit it and let the tool infer from the .uproject).`,
+        ...suggestedEngineRoot ? [`Example engineRoot: ${suggestedEngineRoot}`] : []
+      ].join("\n")
+    );
+  }
+}
+async function resolveEngineRootForUproject(args) {
+  const fromArg = (args.engineRootArg || "").trim();
+  if (fromArg) {
+    if (!isValidEngineRoot(fromArg)) {
+      return { ok: false, errorMessage: `Invalid engineRoot (expected a UE install root containing Engine/\u2026): ${fromArg}`, suggestedEngineRoot: null };
+    }
+    try {
+      await assertEngineRootMatchesUprojectOrThrow({ uprojectPath: args.uprojectPath, engineRoot: fromArg, source: "arg" });
+    } catch (e) {
+      return { ok: false, errorMessage: e instanceof Error ? e.message : String(e), suggestedEngineRoot: null };
+    }
+    return { ok: true, engineRoot: fromArg, source: "arg", engineAssociation: await readUprojectEngineAssociationOrNull(args.uprojectPath) };
+  }
+  const fromEnv = (process.env.UE_ENGINE_ROOT || process.env.ENGINE_ROOT || "").trim();
+  if (fromEnv) {
+    if (!isValidEngineRoot(fromEnv)) {
+      return { ok: false, errorMessage: `ENGINE_ROOT is set but invalid (expected a UE install root containing Engine/\u2026): ${fromEnv}`, suggestedEngineRoot: null };
+    }
+    try {
+      await assertEngineRootMatchesUprojectOrThrow({ uprojectPath: args.uprojectPath, engineRoot: fromEnv, source: "env" });
+    } catch (e) {
+      return { ok: false, errorMessage: e instanceof Error ? e.message : String(e), suggestedEngineRoot: null };
+    }
+    return { ok: true, engineRoot: fromEnv, source: "env", engineAssociation: await readUprojectEngineAssociationOrNull(args.uprojectPath) };
+  }
+  const engineAssociation = await readUprojectEngineAssociationOrNull(args.uprojectPath);
+  if (!engineAssociation) {
+    return {
+      ok: false,
+      errorMessage: "Missing `engineRoot` (and UE_ENGINE_ROOT / ENGINE_ROOT not set). Unable to infer the engine version from the .uproject EngineAssociation.",
+      suggestedEngineRoot: null
+    };
+  }
+  const candidates = engineRootCandidatesForVersion(process.platform, engineAssociation);
+  const valid = candidates.filter((c) => isValidEngineRoot(c));
+  if (valid.length > 0) {
+    return { ok: true, engineRoot: valid[0], source: "uproject", engineAssociation };
+  }
+  return {
+    ok: false,
+    errorMessage: `Missing \`engineRoot\` (and UE_ENGINE_ROOT / ENGINE_ROOT not set). This project targets UE ${engineAssociation.major}.${engineAssociation.minor} but no standard engine install was found.`,
+    suggestedEngineRoot: candidates[0] || null
+  };
+}
 async function runCmdAndCapture(args) {
   return await new Promise((resolvePromise, rejectPromise) => {
     const child = node_child_process.spawn(args.cmd, args.cmdArgs, { stdio: ["ignore", "pipe", "pipe"], cwd: args.cwd, env: args.env });
@@ -6302,7 +7049,9 @@ async function uploadScreenshotViewsForSession(args) {
   const res = await fetch(endpoint, {
     method: "POST",
     headers: {
-      Authorization: `Bearer ${args.token}`
+      // 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
   });
@@ -6338,11 +7087,14 @@ async function startFlockbayServer(client, options) {
   const handler = async (title) => {
     types.logger.debug("[flockbayMCP] Changing title to:", title);
     try {
-      client.sendClaudeSessionMessage({
-        type: "summary",
-        summary: title,
-        leafUuid: node_crypto.randomUUID()
-      });
+      const trimmed = String(title || "").trim();
+      if (!trimmed) {
+        return { success: false, error: "Missing title" };
+      }
+      client.updateMetadata((current) => ({
+        ...current || {},
+        name: trimmed
+      }));
       return { success: true };
     } catch (error) {
       return { success: false, error: String(error) };
@@ -6371,7 +7123,7 @@ async function startFlockbayServer(client, options) {
     const res = await fetch(`${types.configuration.serverUrl.replace(/\/+$/, "")}${pathname}`, {
       method: "POST",
       headers: {
-        Authorization: `Bearer ${client.getAuthToken()}`,
+        Authorization: `Machine ${client.getAuthToken()}`,
         "Content-Type": "application/json"
       },
       body: JSON.stringify(body ?? {})
@@ -6396,6 +7148,166 @@ async function startFlockbayServer(client, options) {
     const meta = client?.metadata;
     return String(meta?.path || "").trim() || process.cwd();
   };
+  const unrealIssueEmitter = new node_events.EventEmitter();
+  const unrealEditorSupervisor = (() => {
+    const state = {
+      lastActivityAtMs: 0,
+      lastReachableAtMs: 0,
+      lastIssueAtMs: 0,
+      lastIssueKey: "",
+      launched: null
+    };
+    const emitIssue = (event) => {
+      const key = `${event.kind}:${event.severity}:${event.message}`;
+      const now = event.detectedAtMs;
+      if (state.lastIssueKey === key && now - state.lastIssueAtMs < 15e3) return;
+      state.lastIssueKey = key;
+      state.lastIssueAtMs = now;
+      unrealIssueEmitter.emit("issue", event);
+      if (unrealIssueEmitter.listenerCount("issue") === 0) {
+        try {
+          const msg = event.kind === "process_exit" ? `Unreal Editor crashed. ${event.message}` : `Unreal Editor is not reachable. ${event.message}`;
+          client.sendSessionEvent({ type: "message", message: msg });
+          const socket = client?.socket;
+          const keyBytes = client?.encryptionKey;
+          if (socket && keyBytes) {
+            const params = encodeBase64(encrypt(keyBytes, {}));
+            socket.emit("rpc-call", { method: `${client.sessionId}:abort`, params }, () => {
+            });
+          }
+        } catch (err) {
+          types.logger.debug("[flockbayMCP] Failed to auto-abort after Unreal issue", err);
+        }
+      }
+    };
+    const getUnrealEditorExe = (engineRoot) => {
+      const root = engineRoot.trim().replace(/[\\/]+$/, "");
+      if (process.platform === "darwin") {
+        return path.join(root, "Engine", "Binaries", "Mac", "UnrealEditor.app", "Contents", "MacOS", "UnrealEditor");
+      }
+      if (process.platform === "win32") {
+        return path.join(root, "Engine", "Binaries", "Win64", "UnrealEditor.exe");
+      }
+      if (process.platform === "linux") {
+        return path.join(root, "Engine", "Binaries", "Linux", "UnrealEditor");
+      }
+      return "";
+    };
+    const runCommandCapture = async (cmd, args) => {
+      return new Promise((resolve) => {
+        const child = node_child_process.spawn(cmd, args, { shell: false, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (c) => stdout += c.toString("utf8"));
+        child.stderr?.on("data", (c) => stderr += c.toString("utf8"));
+        child.on("error", (e) => resolve({ ok: false, stdout, stderr: e instanceof Error ? e.message : String(e) }));
+        child.on("close", (code) => resolve({ ok: code === 0, stdout, stderr }));
+      });
+    };
+    const isUnrealEditorProcessRunningBestEffort = async () => {
+      if (process.platform === "win32") {
+        const res2 = await runCommandCapture("tasklist", ["/FI", "IMAGENAME eq UnrealEditor.exe", "/FO", "CSV", "/NH"]);
+        const out2 = `${res2.stdout}
+${res2.stderr}`.toLowerCase();
+        return out2.includes("unrealeditor.exe");
+      }
+      const res = await runCommandCapture("ps", ["-A", "-o", "comm="]);
+      const out = `${res.stdout}
+${res.stderr}`;
+      return /\bUnrealEditor\b/.test(out) || /\bUE4Editor\b/.test(out) || /\bUE5Editor\b/.test(out);
+    };
+    const tick = async () => {
+      const now = Date.now();
+      const activeWindowMs = 10 * 6e4;
+      const isActive = state.lastActivityAtMs > 0 && now - state.lastActivityAtMs < activeWindowMs || Boolean(state.launched);
+      if (!isActive) return;
+      try {
+        await types.sendUnrealMcpTcpCommand({ type: "ping", params: {}, timeoutMs: 750 });
+        state.lastReachableAtMs = now;
+        return;
+      } catch {
+      }
+      if (state.launched) return;
+      if (!state.lastReachableAtMs || now - state.lastReachableAtMs > activeWindowMs) return;
+      const running = await isUnrealEditorProcessRunningBestEffort().catch(() => true);
+      if (running) return;
+      emitIssue({
+        kind: "unreachable",
+        severity: "warning",
+        detectedAtMs: now,
+        message: "Unreal Editor is no longer reachable (it was reachable earlier). It may have crashed or been closed.",
+        detail: {
+          lastReachableAtMs: state.lastReachableAtMs
+        }
+      });
+    };
+    const interval = setInterval(() => {
+      void tick();
+    }, 2e3);
+    interval.unref();
+    const noteUnrealActivity = () => {
+      state.lastActivityAtMs = Date.now();
+    };
+    const noteUnrealReachable = () => {
+      state.lastReachableAtMs = Date.now();
+    };
+    const launchEditor = async (params) => {
+      const uprojectPath = params.uprojectPath;
+      const engineRoot = params.engineRoot;
+      const extraArgs = Array.isArray(params.extraArgs) ? params.extraArgs.filter((a) => typeof a === "string" && a.trim()) : [];
+      const exe = getUnrealEditorExe(engineRoot);
+      if (!exe) throw new Error(`Unsupported platform for Unreal Editor launch: ${process.platform}`);
+      if (!fs.existsSync(exe)) throw new Error(`Unreal Editor binary not found: ${exe}`);
+      const child = node_child_process.spawn(exe, [uprojectPath, ...extraArgs], { detached: true, stdio: "ignore" });
+      child.unref();
+      const pid = typeof child.pid === "number" ? child.pid : 0;
+      state.launched = {
+        pid,
+        uprojectPath,
+        engineRoot,
+        startedAtMs: Date.now()
+      };
+      child.on("exit", (code, signal) => {
+        const now = Date.now();
+        const exitCode = typeof code === "number" ? code : null;
+        const sig = typeof signal === "string" ? signal : null;
+        const isCrash = sig !== null || exitCode !== null && exitCode !== 0;
+        state.launched = null;
+        if (!isCrash) return;
+        emitIssue({
+          kind: "process_exit",
+          severity: "crash",
+          detectedAtMs: now,
+          message: `Unreal Editor process exited unexpectedly (code=${exitCode ?? "null"} signal=${sig ?? "null"}).`,
+          detail: { exitCode, signal: sig, pid, uprojectPath }
+        });
+      });
+      child.on("error", (err) => {
+        const now = Date.now();
+        state.launched = null;
+        emitIssue({
+          kind: "process_exit",
+          severity: "crash",
+          detectedAtMs: now,
+          message: `Failed to launch Unreal Editor: ${err instanceof Error ? err.message : String(err)}`,
+          detail: { pid, uprojectPath }
+        });
+      });
+      return { pid, exePath: exe };
+    };
+    return {
+      noteUnrealActivity,
+      noteUnrealReachable,
+      launchEditor,
+      stop: () => {
+        try {
+          interval.unref();
+          clearInterval(interval);
+        } catch {
+        }
+      }
+    };
+  })();
   const runGit = async (cmdArgs, cwd, timeoutMs) => {
     const res = await runCmdAndCapture({
       cmd: "git",
@@ -7103,7 +8015,7 @@ ${String(st.stdout || "").trim()}`
       const url = `${types.configuration.serverUrl.replace(/\/+$/, "")}/v1/sessions/${encodeURIComponent(client.sessionId)}/evidence-artifacts?limit=${limit}`;
       const res = await fetch(url, {
         method: "GET",
-        headers: { Authorization: `Bearer ${client.getAuthToken()}`, accept: "application/json" }
+        headers: { Authorization: `Machine ${client.getAuthToken()}`, accept: "application/json" }
       });
       const data = await res.json().catch(() => null);
       if (!res.ok) {
@@ -7128,7 +8040,7 @@ ${String(st.stdout || "").trim()}`
       const url = `${types.configuration.serverUrl.replace(/\/+$/, "")}/v1/sessions/${encodeURIComponent(client.sessionId)}/evidence-artifacts/${encodeURIComponent(id)}`;
       const res = await fetch(url, {
         method: "GET",
-        headers: { Authorization: `Bearer ${client.getAuthToken()}`, accept: "application/json" }
+        headers: { Authorization: `Machine ${client.getAuthToken()}`, accept: "application/json" }
       });
       const data = await res.json().catch(() => null);
       if (!res.ok) {
@@ -7684,6 +8596,7 @@ ${String(st.stdout || "").trim()}`
         }
         return {
           content,
+          views: viewsPayload,
           isError: false
         };
       } catch (error) {
@@ -7698,8 +8611,8 @@ ${String(st.stdout || "").trim()}`
     })
   );
   mcp.registerTool("unreal_latest_screenshots", {
-    title: "Latest Unreal Screenshots",
-    description: "Fetch the latest PNG screenshots from `Saved/Screenshots/Flockbay/` and return a `{ views: [...] }` payload so the app can display them.",
+    title: "Latest Unreal Screenshots (Validation)",
+    description: "Fetch the latest PNG screenshots from `Saved/Screenshots/Flockbay/` (for validation) and return a `{ views: [...] }` payload so the app can display them.",
     inputSchema: {
       uprojectPath: z.z.string().describe("Absolute path to the .uproject file."),
       limit: z.z.number().int().positive().optional().describe("Max number of screenshots to return (default 12)."),
@@ -7784,6 +8697,7 @@ ${String(st.stdout || "").trim()}`
           { type: "text", text: `Found ${views.length} screenshot${views.length === 1 ? "" : "s"} in: ${outDir}` },
           { type: "text", text: JSON.stringify({ views }, null, 2) }
         ],
+        views,
         isError: false
       };
     } catch (error) {
@@ -7819,6 +8733,7 @@ ${String(st.stdout || "").trim()}`
     const name = typeof pluginInfo?.name === "string" ? pluginInfo.name : "UnrealMCP";
     const versionName = typeof pluginInfo?.versionName === "string" ? pluginInfo.versionName : null;
     const baseDir = typeof pluginInfo?.baseDir === "string" ? pluginInfo.baseDir : null;
+    const schemaVersion = typeof pluginInfo?.schemaVersion === "number" ? pluginInfo.schemaVersion : null;
     const commands = Array.isArray(pluginInfo?.commands) ? pluginInfo.commands.filter((c) => typeof c === "string") : [];
     const head = [name, versionName ? `v${versionName}` : null].filter(Boolean).join(" ");
     const cmdText = commands.length > 0 ? commands.slice(0, 60).join(", ") : "(no commands reported)";
@@ -7826,10 +8741,126 @@ ${String(st.stdout || "").trim()}`
     return [
       `UnrealMCP capabilities detected: ${head}`,
       baseDir ? `Plugin path: ${baseDir}` : null,
+      schemaVersion !== null ? `Schema version: ${schemaVersion}` : null,
       `Supported commands: ${cmdText}${truncated}`,
-      `Guidance: avoid guessing; prefer using only supported commands. If you get "Unknown command", run get_plugin_info and adjust.`
+      `Guidance: avoid guessing; prefer using get_command_schema / list_capabilities when unsure about params.`
     ].filter(Boolean).join("\n");
   }
+  mcp.registerTool("unreal_editor_launch", {
+    title: "Unreal Editor: Launch Project",
+    description: "Launch Unreal Editor for a given .uproject (no auto-restart). If the editor later crashes or becomes unreachable, Flockbay will abort the current agent run and report it in the chat.",
+    inputSchema: {
+      uprojectPath: z.z.string().describe("Absolute path to the .uproject file."),
+      engineRoot: z.z.string().optional().describe("Optional Unreal Engine install root. Defaults to ENGINE_ROOT / UE_ENGINE_ROOT, or inferred from EngineAssociation when possible."),
+      extraArgs: z.z.array(z.z.string()).optional().describe("Additional UnrealEditor command-line args (advanced).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_editor_launch", args, async () => {
+    const uprojectPath = typeof args?.uprojectPath === "string" ? String(args.uprojectPath).trim() : "";
+    const engineRootArg = typeof args?.engineRoot === "string" ? String(args.engineRoot).trim() : "";
+    const extraArgs = Array.isArray(args?.extraArgs) ? args.extraArgs : [];
+    if (!uprojectPath || !uprojectPath.toLowerCase().endsWith(".uproject") || !path.isAbsolute(uprojectPath)) {
+      return {
+        content: [{ type: "text", text: `Invalid uprojectPath (must be an absolute path to *.uproject): ${String(uprojectPath)}` }],
+        isError: true
+      };
+    }
+    if (!fs.existsSync(uprojectPath)) {
+      return { content: [{ type: "text", text: `uprojectPath not found: ${uprojectPath}` }], isError: true };
+    }
+    const resolved = await resolveEngineRootForUproject({ uprojectPath, engineRootArg: engineRootArg || null });
+    if (!resolved.ok) {
+      return {
+        content: [
+          { type: "text", text: `Unable to resolve engineRoot for this project.` },
+          { type: "text", text: resolved.errorMessage },
+          ...resolved.suggestedEngineRoot ? [{ type: "text", text: `Suggested engineRoot: ${resolved.suggestedEngineRoot}` }] : []
+        ],
+        isError: true
+      };
+    }
+    unrealEditorSupervisor.noteUnrealActivity();
+    const launched = await unrealEditorSupervisor.launchEditor({
+      uprojectPath,
+      engineRoot: resolved.engineRoot,
+      extraArgs
+    });
+    return {
+      content: [
+        { type: "text", text: `Launched Unreal Editor for: ${uprojectPath}` },
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              engineRoot: resolved.engineRoot,
+              engineRootSource: resolved.source,
+              pid: launched.pid,
+              exePath: launched.exePath
+            },
+            null,
+            2
+          )
+        },
+        { type: "text", text: "Next: wait for the editor to finish loading, then use UnrealMCP tools (ping / get_plugin_info / play_in_editor / etc)." }
+      ],
+      isError: false
+    };
+  }));
+  mcp.registerTool("unreal_build_project", {
+    title: "Unreal Build Project (UBT)",
+    description: "Build the project via Unreal Build Tool (via Engine/Build/BatchFiles/Build.*). Returns structured errors (file/line) and a log path for deep debugging.",
+    inputSchema: {
+      uprojectPath: z.z.string().describe("Absolute path to the .uproject file."),
+      engineRoot: z.z.string().optional().describe("Optional Unreal Engine install root. Defaults to ENGINE_ROOT / UE_ENGINE_ROOT, or inferred from EngineAssociation when possible."),
+      configuration: z.z.enum(["Debug", "DebugGame", "Development", "Shipping"]).optional().describe("Build configuration (default Development)."),
+      target: z.z.enum(["Editor", "Game"]).optional().describe("Build target (default Editor)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Timeout in ms (default 20m)."),
+      issuesLimit: z.z.number().int().positive().optional().describe("Max issues to return (default 250, max 2000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_build_project", args, async () => {
+    const uprojectPath = typeof args?.uprojectPath === "string" ? String(args.uprojectPath).trim() : "";
+    const engineRootArg = typeof args?.engineRoot === "string" ? String(args.engineRoot).trim() : "";
+    const timeoutMs = typeof args?.timeoutMs === "number" ? args.timeoutMs : void 0;
+    if (!uprojectPath || !uprojectPath.toLowerCase().endsWith(".uproject") || !path.isAbsolute(uprojectPath)) {
+      return {
+        content: [{ type: "text", text: `Invalid uprojectPath (must be an absolute path to *.uproject): ${String(uprojectPath)}` }],
+        isError: true
+      };
+    }
+    if (!fs.existsSync(uprojectPath)) {
+      return { content: [{ type: "text", text: `uprojectPath not found: ${uprojectPath}` }], isError: true };
+    }
+    const resolved = await resolveEngineRootForUproject({ uprojectPath, engineRootArg: engineRootArg || null });
+    if (!resolved.ok) {
+      return {
+        content: [
+          { type: "text", text: `Unable to resolve engineRoot for this project.` },
+          { type: "text", text: resolved.errorMessage },
+          ...resolved.suggestedEngineRoot ? [{ type: "text", text: `Suggested engineRoot: ${resolved.suggestedEngineRoot}` }] : []
+        ],
+        isError: true
+      };
+    }
+    const configuration2 = args?.configuration ?? "Development";
+    const target = args?.target ?? "Editor";
+    const issuesLimit = typeof args?.issuesLimit === "number" ? args.issuesLimit : void 0;
+    const result = await buildUnrealProject({
+      uprojectPath,
+      engineRoot: resolved.engineRoot,
+      configuration: configuration2,
+      target,
+      timeoutMs,
+      issuesLimit
+    });
+    const payload = { ...result, engineRoot: resolved.engineRoot, engineRootSource: resolved.source };
+    return {
+      content: [
+        { type: "text", text: result.ok ? "Build succeeded." : "Build failed." },
+        ...result.logPath ? [{ type: "text", text: `Log: ${result.logPath}` }] : [],
+        { type: "text", text: JSON.stringify(payload, null, 2) }
+      ],
+      isError: !result.ok
+    };
+  }));
   mcp.registerTool("unreal_mcp_command", {
     title: "Unreal Editor Command (UnrealMCP)",
     description: "Send a single UnrealMCP command to the running Unreal Editor (engine plugin) and return the JSON response. Requires Unreal Editor running with the UnrealMCP plugin enabled.",
@@ -7842,10 +8873,12 @@ ${String(st.stdout || "").trim()}`
     const type = String(args.type || "").trim();
     const params = args.params && typeof args.params === "object" ? args.params : {};
     const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
     try {
       const pluginInfoWasCached = Boolean(unrealMcpPluginInfoCache);
       const pluginInfo = type !== "get_plugin_info" ? await getUnrealMcpPluginInfoBestEffort(timeoutMs) : null;
       const response = await types.sendUnrealMcpTcpCommand({ type, params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       return {
         content: [
           { type: "text", text: `UnrealMCP command ok: ${type}` },
@@ -7868,16 +8901,928 @@ ${String(st.stdout || "").trim()}`
       };
     }
   }));
-  mcp.registerTool("unreal_mcp_get_actors_in_level", {
-    title: "Unreal Actors In Level (UnrealMCP)",
-    description: "List all actors in the current Unreal Editor level via the UnrealMCP engine plugin. Requires Unreal Editor running with the UnrealMCP plugin enabled.",
+  mcp.registerTool("unreal_mcp_list_capabilities", {
+    title: "Unreal MCP: Capabilities",
+    description: "Query the running UnrealMCP plugin for its build info, supported command list, and capability flags. Use this to avoid guessing tool availability/behavior.",
+    inputSchema: {
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 2000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_list_capabilities", args, async () => {
+    const timeoutMs = args?.timeoutMs ?? 2e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    const response = await types.sendUnrealMcpTcpCommand({ type: "list_capabilities", params: {}, timeoutMs });
+    unrealEditorSupervisor.noteUnrealReachable();
+    return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }], isError: false };
+  }));
+  mcp.registerTool("unreal_mcp_get_command_schema", {
+    title: "Unreal MCP: Command Schema",
+    description: "Fetch a per-command schema from the running UnrealMCP plugin (required params, aliases, examples). If command is omitted, returns all known schemas (can be large).",
     inputSchema: {
+      command: z.z.string().optional().describe('Command type to fetch schema for (e.g. "create_blueprint").'),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 2000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_get_command_schema", args, async () => {
+    const timeoutMs = args?.timeoutMs ?? 2e3;
+    const command = typeof args?.command === "string" ? String(args.command).trim() : "";
+    unrealEditorSupervisor.noteUnrealActivity();
+    const response = await types.sendUnrealMcpTcpCommand({
+      type: "get_command_schema",
+      params: command ? { command } : {},
+      timeoutMs
+    });
+    unrealEditorSupervisor.noteUnrealReachable();
+    return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }], isError: false };
+  }));
+  mcp.registerTool("unreal_mcp_search_blueprint_functions", {
+    title: "Unreal MCP: Search Blueprint Functions",
+    description: "Search for Blueprint-callable functions and return candidates (owner class path + signature hints) to use with add_blueprint_function_node.",
+    inputSchema: {
+      query: z.z.string().describe('Substring to search for (e.g. "MakeVector", "SetRelativeLocation").'),
+      target: z.z.string().optional().describe('Optional target class constraint (e.g. "KismetMathLibrary").'),
+      limit: z.z.number().int().positive().optional().describe("Max results (default 25)."),
       timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
     }
-  }, async (args) => runWithMcpToolCard("unreal_mcp_get_actors_in_level", args, async () => {
+  }, async (args) => runWithMcpToolCard("unreal_mcp_search_blueprint_functions", args, async () => {
+    const timeoutMs = args?.timeoutMs ?? 5e3;
+    const query = String(args.query || "").trim();
+    const target = typeof args?.target === "string" ? String(args.target).trim() : "";
+    const limit = typeof args?.limit === "number" ? args.limit : void 0;
+    unrealEditorSupervisor.noteUnrealActivity();
+    const params = { query };
+    if (target) params.target = target;
+    if (typeof limit === "number") params.limit = limit;
+    const response = await types.sendUnrealMcpTcpCommand({ type: "search_blueprint_functions", params, timeoutMs });
+    unrealEditorSupervisor.noteUnrealReachable();
+    return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }], isError: false };
+  }));
+  mcp.registerTool("unreal_mcp_resolve_blueprint_function", {
+    title: "Unreal MCP: Resolve Blueprint Function",
+    description: 'Resolve a Blueprint-callable function to an explicit owner class path usable with add_blueprint_function_node (reduces "Function not found" guesswork).',
+    inputSchema: {
+      functionName: z.z.string().describe('Function name to resolve (e.g. "MakeVector").'),
+      target: z.z.string().optional().describe("Optional target class constraint."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_resolve_blueprint_function", args, async () => {
+    const timeoutMs = args?.timeoutMs ?? 5e3;
+    const functionName = String(args.functionName || "").trim();
+    const target = typeof args?.target === "string" ? String(args.target).trim() : "";
+    unrealEditorSupervisor.noteUnrealActivity();
+    const params = { function_name: functionName };
+    if (target) params.target = target;
+    const response = await types.sendUnrealMcpTcpCommand({ type: "resolve_blueprint_function", params, timeoutMs });
+    unrealEditorSupervisor.noteUnrealReachable();
+    return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }], isError: false };
+  }));
+  mcp.registerTool("unreal_mcp_search_assets", {
+    title: "Unreal Search Assets (UnrealMCP)",
+    description: "Search for assets in the current Unreal project via the UnrealMCP engine plugin (AssetRegistry-backed). Returns object paths suitable for place_asset/spawn_actor.",
+    inputSchema: {
+      query: z.z.string().optional().describe("Fuzzy search string (name/path)."),
+      class: z.z.union([z.z.string(), z.z.array(z.z.string())]).optional().describe('Optional asset class filter (e.g. "StaticMesh", "Blueprint", "Material").'),
+      root: z.z.string().optional().describe('Root path to search (default "/Game/").'),
+      limit: z.z.number().int().positive().optional().describe("Max results (default 25, max 200)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_search_assets", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const params = {};
+      if (typeof args.query === "string" && args.query.trim()) params.query = args.query.trim();
+      if (typeof args.root === "string" && args.root.trim()) params.root = args.root.trim();
+      if (typeof args.limit === "number" && Number.isFinite(args.limit)) params.limit = args.limit;
+      if (typeof args.class === "string" && args.class.trim()) params.class = args.class.trim();
+      if (Array.isArray(args.class)) params.class = args.class;
+      const response = await types.sendUnrealMcpTcpCommand({ type: "search_assets", params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Unreal assets search ok." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Unreal assets search failed." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_get_asset_info", {
+    title: "Unreal Asset Info (UnrealMCP)",
+    description: "Get metadata for a single Unreal asset (class/path + optional dependencies) via the UnrealMCP engine plugin.",
+    inputSchema: {
+      objectPath: z.z.string().describe('Unreal asset object path (e.g. "/Game/MyPack/MyMesh.MyMesh").'),
+      includeDependencies: z.z.boolean().optional().describe("Include package dependencies (default false)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_get_asset_info", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const params = { objectPath: String(args.objectPath || "").trim() };
+      if (typeof args.includeDependencies === "boolean") params.includeDependencies = args.includeDependencies;
+      const response = await types.sendUnrealMcpTcpCommand({ type: "get_asset_info", params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Unreal asset info ok." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Unreal asset info failed." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_list_asset_packs", {
+    title: "Unreal List Asset Packs (UnrealMCP)",
+    description: 'List top-level /Game content folders (best-effort "asset packs") via the UnrealMCP engine plugin.',
+    inputSchema: {
+      limit: z.z.number().int().positive().optional().describe("Max number of packs (default 200)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_list_asset_packs", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const params = {};
+      if (typeof args.limit === "number" && Number.isFinite(args.limit)) params.limit = args.limit;
+      const response = await types.sendUnrealMcpTcpCommand({ type: "list_asset_packs", params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Unreal asset packs list ok." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Unreal asset packs list failed." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_place_asset", {
+    title: "Unreal Place Asset (UnrealMCP)",
+    description: "Place an asset into the current Unreal level by object path (StaticMesh/Blueprint). Fails if PIE is running to avoid crashes.",
+    inputSchema: {
+      objectPath: z.z.string().describe('Unreal asset object path (e.g. "/Game/MyPack/MyMesh.MyMesh").'),
+      name: z.z.string().optional().describe("Optional actor name (default: derived from asset name)."),
+      location: z.z.array(z.z.number()).length(3).optional().describe("Spawn location [X,Y,Z] in cm."),
+      rotation: z.z.array(z.z.number()).length(3).optional().describe("Spawn rotation [Pitch,Yaw,Roll] in degrees."),
+      scale: z.z.array(z.z.number()).length(3).optional().describe("Spawn scale [X,Y,Z]."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_place_asset", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const params = { objectPath: String(args.objectPath || "").trim() };
+      if (typeof args.name === "string" && args.name.trim()) params.name = args.name.trim();
+      if (Array.isArray(args.location)) params.location = args.location;
+      if (Array.isArray(args.rotation)) params.rotation = args.rotation;
+      if (Array.isArray(args.scale)) params.scale = args.scale;
+      const response = await types.sendUnrealMcpTcpCommand({ type: "place_asset", params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Placed asset into Unreal level." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Failed to place asset into Unreal level." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) },
+          { type: "text", text: "Tip: use unreal_mcp_get_play_in_editor_status and stop PIE before placing assets." }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_get_editor_context", {
+    title: "Unreal Editor Context (UnrealMCP)",
+    description: "Return a compact snapshot of editor context: map, selection, and active viewport camera (if any).",
+    inputSchema: {
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_get_editor_context", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const response = await types.sendUnrealMcpTcpCommand({ type: "get_editor_context", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Fetched Unreal Editor context." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Failed to fetch Unreal Editor context." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_get_player_context", {
+    title: "Unreal Player Context (PIE)",
+    description: "Return a compact snapshot of runtime player context (PIE): isPlaying, pawn transform, and camera transform.",
+    inputSchema: {
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_get_player_context", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const response = await types.sendUnrealMcpTcpCommand({ type: "get_player_context", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Fetched player context." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Failed to fetch player context." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_raycast_from_camera", {
+    title: "Unreal Raycast From Camera (Editor/PIE)",
+    description: "Raycast from the editor viewport camera or the PIE player camera to turn \u201Cthat surface\u201D into an exact hit location and normal.",
+    inputSchema: {
+      source: z.z.enum(["editor", "pie"]).optional().describe("Camera source (default editor)."),
+      maxDistance: z.z.number().positive().optional().describe("Max distance in cm (default 10000)."),
+      ignoreActors: z.z.array(z.z.string()).optional().describe("Actor names/labels to ignore (best-effort)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_raycast_from_camera", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const params = {};
+      if (args.source) params.source = args.source;
+      if (typeof args.maxDistance === "number" && Number.isFinite(args.maxDistance)) params.maxDistance = args.maxDistance;
+      if (Array.isArray(args.ignoreActors)) params.ignoreActors = args.ignoreActors;
+      const response = await types.sendUnrealMcpTcpCommand({ type: "raycast_from_camera", params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Raycast completed." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Raycast failed." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_raycast_down", {
+    title: "Unreal Raycast Down (Drop To Ground)",
+    description: "Raycast straight down from a given startLocation to find ground/surface beneath. Useful for drop-to-ground placement.",
+    inputSchema: {
+      source: z.z.enum(["editor", "pie"]).optional().describe("World source (default editor)."),
+      startLocation: z.z.array(z.z.number()).length(3).describe("Start location [X,Y,Z] in cm."),
+      maxDistance: z.z.number().positive().optional().describe("Max distance in cm (default 100000)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_raycast_down", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const params = { startLocation: args.startLocation };
+      if (args.source) params.source = args.source;
+      if (typeof args.maxDistance === "number" && Number.isFinite(args.maxDistance)) params.maxDistance = args.maxDistance;
+      const response = await types.sendUnrealMcpTcpCommand({ type: "raycast_down", params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Raycast-down completed." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Raycast-down failed." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_get_actor_transform", {
+    title: "Unreal Actor Transform (UnrealMCP)",
+    description: "Get a single actor transform (location/rotation/scale) by actor name or label (best-effort).",
+    inputSchema: {
+      name: z.z.string().describe("Actor name or label."),
+      source: z.z.enum(["editor", "pie"]).optional().describe("World source (default editor)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_get_actor_transform", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const params = { name: String(args.name || "").trim() };
+      if (args.source) params.source = args.source;
+      const response = await types.sendUnrealMcpTcpCommand({ type: "get_actor_transform", params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Fetched actor transform." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Failed to fetch actor transform." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_get_actor_bounds", {
+    title: "Unreal Actor Bounds (UnrealMCP)",
+    description: "Get a single actor bounds (origin/extent + min/max) by actor name or label (best-effort).",
+    inputSchema: {
+      name: z.z.string().describe("Actor name or label."),
+      source: z.z.enum(["editor", "pie"]).optional().describe("World source (default editor)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_get_actor_bounds", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const params = { name: String(args.name || "").trim() };
+      if (args.source) params.source = args.source;
+      const response = await types.sendUnrealMcpTcpCommand({ type: "get_actor_bounds", params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Fetched actor bounds." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Failed to fetch actor bounds." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_create_landscape", {
+    title: "Unreal Create Landscape (UnrealMCP)",
+    description: "Create a new Landscape in the current editor level via the UnrealMCP engine plugin. Requires Unreal Editor running with the UnrealMCP plugin enabled. Fails if PIE is running.",
+    inputSchema: {
+      name: z.z.string().describe("New landscape actor name (must be unique)."),
+      componentCountX: z.z.number().int().positive().optional().describe("Number of components in X (default 8)."),
+      componentCountY: z.z.number().int().positive().optional().describe("Number of components in Y (default 8)."),
+      sectionsPerComponent: z.z.number().int().optional().describe("Sections per component (1 or 2, default 1)."),
+      quadsPerSection: z.z.number().int().positive().optional().describe("Quads per section (default 63)."),
+      location: z.z.array(z.z.number()).length(3).optional().describe("Center location [X,Y,Z] in cm (default [0,0,0])."),
+      rotation: z.z.array(z.z.number()).length(3).optional().describe("Rotation [Pitch,Yaw,Roll] in degrees (default [0,0,0])."),
+      scale: z.z.array(z.z.number()).length(3).optional().describe("Scale [X,Y,Z] (default [100,100,100])."),
+      materialPath: z.z.string().optional().describe('Optional landscape material object path (e.g. "/Game/\u2026/M_Landscape.M_Landscape").'),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 30000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_create_landscape", args, async () => {
+    const timeoutMs = args?.timeoutMs ?? 3e4;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const params = {
+        name: String(args?.name || "").trim()
+      };
+      if (!params.name) throw new Error("name is required.");
+      if (typeof args?.componentCountX === "number") params.componentCountX = args.componentCountX;
+      if (typeof args?.componentCountY === "number") params.componentCountY = args.componentCountY;
+      if (typeof args?.sectionsPerComponent === "number") params.sectionsPerComponent = args.sectionsPerComponent;
+      if (typeof args?.quadsPerSection === "number") params.quadsPerSection = args.quadsPerSection;
+      if (Array.isArray(args?.location)) params.location = args.location;
+      if (Array.isArray(args?.rotation)) params.rotation = args.rotation;
+      if (Array.isArray(args?.scale)) params.scale = args.scale;
+      if (typeof args?.materialPath === "string" && args.materialPath.trim()) {
+        params.materialPath = args.materialPath.trim();
+      }
+      const response = await types.sendUnrealMcpTcpCommand({ type: "create_landscape", params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Landscape created." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Failed to create landscape." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) },
+          { type: "text", text: "Tip: stop PIE before creating a landscape." }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_map_check", {
+    title: "Unreal Map Check (UnrealMCP)",
+    description: "Run Unreal Map Check and return structured issues. Uses Unreal\u2019s Message Log to capture results. Fails if PIE is running to avoid editor instability.",
+    inputSchema: {
+      includeWarnings: z.z.boolean().optional().describe("Include warnings in the issues list (default true)."),
+      limit: z.z.number().int().positive().optional().describe("Max number of issues to return (default 200, max 1000)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 15000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_map_check", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 15e3;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const params = {};
+      if (typeof args.includeWarnings === "boolean") params.includeWarnings = args.includeWarnings;
+      if (typeof args.limit === "number" && Number.isFinite(args.limit)) params.limit = args.limit;
+      const response = await types.sendUnrealMcpTcpCommand({ type: "map_check", params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Map Check completed." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Map Check failed." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) },
+          { type: "text", text: "Tip: stop PIE before running map_check." }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_compile_blueprints_all", {
+    title: "Unreal Compile All Blueprints (UnrealMCP)",
+    description: "Compile all Blueprints (optionally under specific content paths) and return a structured list of compile messages. Fails if PIE is running.",
+    inputSchema: {
+      paths: z.z.array(z.z.string()).optional().describe('Root content paths to search (default ["/Game"]).'),
+      includeWarnings: z.z.boolean().optional().describe("Include warnings in the per-blueprint messages list (default true)."),
+      limit: z.z.number().int().positive().optional().describe("Max number of blueprints to compile (default 500, max 10000)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 60000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_compile_blueprints_all", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 6e4;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const params = {};
+      if (Array.isArray(args.paths)) params.paths = args.paths;
+      if (typeof args.includeWarnings === "boolean") params.includeWarnings = args.includeWarnings;
+      if (typeof args.limit === "number" && Number.isFinite(args.limit)) params.limit = args.limit;
+      const response = await types.sendUnrealMcpTcpCommand({ type: "compile_blueprints_all", params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Blueprint compile completed." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Blueprint compile failed." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) },
+          { type: "text", text: "Tip: stop PIE before compiling Blueprints." }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_save_all", {
+    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.z.number().int().positive().optional().describe("Socket timeout in ms (default 60000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_save_all", args, async () => {
+    const timeoutMs = args?.timeoutMs ?? 6e4;
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const response = await types.sendUnrealMcpTcpCommand({ type: "save_all", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
+      return {
+        content: [
+          { type: "text", text: "Save all completed." },
+          { type: "text", text: JSON.stringify(response, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Save all failed." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) },
+          { type: "text", text: "Tip: stop PIE, resolve any editor save prompts/errors (Save As, checkout), then retry." }
+        ],
+        isError: true
+      };
+    }
+  }));
+  const vec = {
+    add: (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]],
+    sub: (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]],
+    mul: (a, s) => [a[0] * s, a[1] * s, a[2] * s],
+    dot: (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2],
+    len: (a) => Math.sqrt(a[0] * a[0] + a[1] * a[1] + a[2] * a[2]),
+    norm: (a) => {
+      const l = Math.sqrt(a[0] * a[0] + a[1] * a[1] + a[2] * a[2]);
+      if (!Number.isFinite(l) || l <= 1e-8) return [0, 0, 0];
+      return [a[0] / l, a[1] / l, a[2] / l];
+    },
+    cross: (a, b) => [
+      a[1] * b[2] - a[2] * b[1],
+      a[2] * b[0] - a[0] * b[2],
+      a[0] * b[1] - a[1] * b[0]
+    ],
+    isFinite3: (a) => Array.isArray(a) && a.length === 3 && a.every((x) => typeof x === "number" && Number.isFinite(x))
+  };
+  function degToRad(deg) {
+    return deg * Math.PI / 180;
+  }
+  function radToDeg(rad) {
+    return rad * 180 / Math.PI;
+  }
+  function forwardRightUpFromRotator(rot) {
+    const pitch = degToRad(rot[0]);
+    const yaw = degToRad(rot[1]);
+    const roll = degToRad(rot[2]);
+    const cp = Math.cos(pitch);
+    const sp = Math.sin(pitch);
+    const cy = Math.cos(yaw);
+    const sy = Math.sin(yaw);
+    const cr = Math.cos(roll);
+    const sr = Math.sin(roll);
+    const forward = [cp * cy, cp * sy, sp];
+    const right = [
+      sr * sp * cy + cr * -sy,
+      sr * sp * sy + cr * cy,
+      -sr * cp
+    ];
+    const up = [
+      cr * sp * cy + -sr * -sy,
+      cr * sp * sy + -sr * cy,
+      cr * cp
+    ];
+    return { forward: vec.norm(forward), right: vec.norm(right), up: vec.norm(up) };
+  }
+  function rotatorFromBasis(args) {
+    const f = vec.norm(args.forward);
+    const r = vec.norm(args.right);
+    const u = vec.norm(args.up);
+    const yaw = radToDeg(Math.atan2(f[1], f[0]));
+    const pitch = radToDeg(Math.atan2(f[2], Math.sqrt(f[0] * f[0] + f[1] * f[1])));
+    const roll = radToDeg(Math.atan2(r[2], u[2]));
+    return [pitch, yaw, roll];
+  }
+  function unwrapUnrealMcpResult(raw) {
+    if (raw?.result && typeof raw.result === "object") return raw.result;
+    return raw;
+  }
+  mcp.registerTool("unreal_place_asset_relative", {
+    title: "Unreal Place Asset Relative (Context-Aware)",
+    description: "High-level helper built from context/raycast primitives: place an asset relative to selection/camera/player/hit result, with optional align-to-surface and drop-to-ground.",
+    inputSchema: {
+      objectPath: z.z.string().describe('Unreal asset object path (e.g. "/Game/MyPack/MyMesh.MyMesh").'),
+      name: z.z.string().optional().describe("Optional actor name (default: derived from asset name)."),
+      anchor: z.z.enum(["selection", "editor_camera", "player", "player_camera", "hit_result", "actor"]).describe("Reference anchor for placement."),
+      actorName: z.z.string().optional().describe('When anchor="actor", the actor name/label to anchor to.'),
+      offset: z.z.array(z.z.number()).length(3).optional().describe("Offset in anchor local axes [forwardCm, rightCm, upCm] (default [200,0,0])."),
+      alignToSurface: z.z.boolean().optional().describe("When using hit_result or drop-to-ground hits, align actor up to hit normal (default false)."),
+      dropToGround: z.z.boolean().optional().describe("After computing target location, raycast down and snap to the hit location (default false)."),
+      raySource: z.z.enum(["editor", "pie"]).optional().describe('When anchor="hit_result", which camera to raycast from (default editor).'),
+      maxDistance: z.z.number().positive().optional().describe("Raycast max distance in cm (default 10000)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 8000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_place_asset_relative", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 8e3;
+    const offset = Array.isArray(args.offset) && args.offset.length === 3 ? args.offset : [200, 0, 0];
+    const alignToSurface = args.alignToSurface ?? false;
+    const dropToGround = args.dropToGround ?? false;
+    const maxDistance = typeof args.maxDistance === "number" ? args.maxDistance : 1e4;
+    const raySource = args.raySource ?? "editor";
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const anchorRaw = String(args.anchor || "").trim();
+      const anchor = anchorRaw === "player" ? "player_camera" : anchorRaw;
+      const objectPath = String(args.objectPath || "").trim();
+      if (!objectPath) throw new Error("Missing objectPath.");
+      if (!vec.isFinite3(offset)) throw new Error("Invalid offset (expected [forward,right,up] numbers).");
+      let origin = null;
+      let rot = null;
+      let surfaceNormal = null;
+      if (anchor === "selection" || anchor === "editor_camera") {
+        const ctxRaw = await types.sendUnrealMcpTcpCommand({ type: "get_editor_context", params: {}, timeoutMs });
+        unrealEditorSupervisor.noteUnrealReachable();
+        const ctx = unwrapUnrealMcpResult(ctxRaw);
+        if (anchor === "selection") {
+          const sel = Array.isArray(ctx?.selection) ? ctx.selection : [];
+          if (sel.length === 0) throw new Error("No selected actors in Unreal Editor. Select an actor and retry.");
+          const first = sel[0];
+          origin = Array.isArray(first?.location) ? first.location : null;
+          rot = Array.isArray(first?.rotation) ? first.rotation : null;
+        } else {
+          const cam = ctx?.viewportCamera;
+          if (!cam || cam === null) throw new Error("No active viewport camera. Click the viewport and retry.");
+          origin = Array.isArray(cam?.location) ? cam.location : null;
+          rot = Array.isArray(cam?.rotation) ? cam.rotation : null;
+        }
+      } else if (anchor === "player_camera") {
+        const pcRaw = await types.sendUnrealMcpTcpCommand({ type: "get_player_context", params: {}, timeoutMs });
+        unrealEditorSupervisor.noteUnrealReachable();
+        const pc = unwrapUnrealMcpResult(pcRaw);
+        if (!pc?.isPlaying) throw new Error("PIE is not running. Start PIE and retry (or use editor_camera/selection anchors).");
+        const cam = pc?.camera;
+        origin = Array.isArray(cam?.location) ? cam.location : null;
+        rot = Array.isArray(cam?.rotation) ? cam.rotation : null;
+      } else if (anchor === "actor") {
+        const actorName = String(args.actorName || "").trim();
+        if (!actorName) throw new Error('anchor="actor" requires actorName.');
+        const tRaw = await types.sendUnrealMcpTcpCommand({ type: "get_actor_transform", params: { name: actorName, source: "editor" }, timeoutMs });
+        unrealEditorSupervisor.noteUnrealReachable();
+        const t = unwrapUnrealMcpResult(tRaw);
+        origin = Array.isArray(t?.location) ? t.location : null;
+        rot = Array.isArray(t?.rotation) ? t.rotation : null;
+      } else if (anchor === "hit_result") {
+        const hitRaw = await types.sendUnrealMcpTcpCommand({
+          type: "raycast_from_camera",
+          params: { source: raySource, maxDistance },
+          timeoutMs
+        });
+        unrealEditorSupervisor.noteUnrealReachable();
+        const hit = unwrapUnrealMcpResult(hitRaw);
+        if (!hit?.hit) throw new Error("Raycast did not hit anything.");
+        origin = Array.isArray(hit?.location) ? hit.location : null;
+        surfaceNormal = Array.isArray(hit?.normal) ? hit.normal : null;
+        const ctxRot = raySource === "pie" ? unwrapUnrealMcpResult(await types.sendUnrealMcpTcpCommand({ type: "get_player_context", params: {}, timeoutMs }))?.camera?.rotation : unwrapUnrealMcpResult(await types.sendUnrealMcpTcpCommand({ type: "get_editor_context", params: {}, timeoutMs }))?.viewportCamera?.rotation;
+        rot = Array.isArray(ctxRot) ? ctxRot : [0, 0, 0];
+      } else {
+        throw new Error(`Unknown anchor: ${anchor}`);
+      }
+      if (!vec.isFinite3(origin)) throw new Error("Anchor origin is missing or invalid.");
+      if (!rot || !vec.isFinite3(rot)) throw new Error("Anchor rotation is missing or invalid.");
+      const basis = forwardRightUpFromRotator(rot);
+      let target = vec.add(origin, vec.add(vec.mul(basis.forward, offset[0]), vec.add(vec.mul(basis.right, offset[1]), vec.mul(basis.up, offset[2]))));
+      let finalNormal = surfaceNormal;
+      if (dropToGround) {
+        const start = vec.add(target, [0, 0, 1e4]);
+        const downRaw = await types.sendUnrealMcpTcpCommand({
+          type: "raycast_down",
+          params: { source: "editor", startLocation: start, maxDistance: 2e5 },
+          timeoutMs
+        });
+        unrealEditorSupervisor.noteUnrealReachable();
+        const down = unwrapUnrealMcpResult(downRaw);
+        if (down?.hit && Array.isArray(down?.location)) {
+          target = down.location;
+          if (Array.isArray(down?.normal)) finalNormal = down.normal;
+        } else {
+          throw new Error("dropToGround=true but raycast_down did not hit anything.");
+        }
+      }
+      let outRot = rot;
+      if (alignToSurface && vec.isFinite3(finalNormal)) {
+        const up = vec.norm(finalNormal);
+        let fwd = basis.forward;
+        fwd = vec.sub(fwd, vec.mul(up, vec.dot(fwd, up)));
+        if (vec.len(fwd) <= 1e-4) {
+          fwd = vec.cross([0, 1, 0], up);
+        }
+        fwd = vec.norm(fwd);
+        const right = vec.norm(vec.cross(up, fwd));
+        const fixedFwd = vec.norm(vec.cross(right, up));
+        outRot = rotatorFromBasis({ forward: fixedFwd, right, up });
+      }
+      const params = {
+        objectPath,
+        ...typeof args.name === "string" && args.name.trim() ? { name: args.name.trim() } : {},
+        location: target,
+        rotation: outRot
+      };
+      const placed = await types.sendUnrealMcpTcpCommand({ type: "place_asset", params, timeoutMs: Math.max(timeoutMs, 1e4) });
+      unrealEditorSupervisor.noteUnrealReachable();
+      const payload = {
+        anchor,
+        origin,
+        offset,
+        location: target,
+        rotation: outRot,
+        ...finalNormal ? { normal: finalNormal } : {},
+        placed
+      };
+      return {
+        content: [
+          { type: "text", text: "Placed asset relative to context." },
+          { type: "text", text: JSON.stringify(payload, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Failed to place asset relative to context." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_spawn_actor_relative", {
+    title: "Unreal Spawn Actor Relative (Context-Aware)",
+    description: "High-level helper built from context/raycast primitives: spawn an actor type relative to selection/camera/player/hit result.",
+    inputSchema: {
+      type: z.z.string().describe('Actor class/type (e.g. "PointLight", "CameraActor", "StaticMeshActor").'),
+      name: z.z.string().describe("Actor name."),
+      anchor: z.z.enum(["selection", "editor_camera", "player", "player_camera", "hit_result", "actor"]).describe("Reference anchor for placement."),
+      actorName: z.z.string().optional().describe('When anchor="actor", the actor name/label to anchor to.'),
+      offset: z.z.array(z.z.number()).length(3).optional().describe("Offset in anchor local axes [forwardCm, rightCm, upCm] (default [200,0,0])."),
+      alignToSurface: z.z.boolean().optional().describe("When using hit_result or drop-to-ground hits, align actor up to hit normal (default false)."),
+      dropToGround: z.z.boolean().optional().describe("After computing target location, raycast down and snap to the hit location (default false)."),
+      raySource: z.z.enum(["editor", "pie"]).optional().describe('When anchor="hit_result", which camera to raycast from (default editor).'),
+      maxDistance: z.z.number().positive().optional().describe("Raycast max distance in cm (default 10000)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 8000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_spawn_actor_relative", args, async () => {
+    const timeoutMs = args.timeoutMs ?? 8e3;
+    const offset = Array.isArray(args.offset) && args.offset.length === 3 ? args.offset : [200, 0, 0];
+    const alignToSurface = args.alignToSurface ?? false;
+    const dropToGround = args.dropToGround ?? false;
+    const maxDistance = typeof args.maxDistance === "number" ? args.maxDistance : 1e4;
+    const raySource = args.raySource ?? "editor";
+    unrealEditorSupervisor.noteUnrealActivity();
+    try {
+      const type = String(args.type || "").trim();
+      const name = String(args.name || "").trim();
+      const anchorRaw = String(args.anchor || "").trim();
+      const anchor = anchorRaw === "player" ? "player_camera" : anchorRaw;
+      if (!type) throw new Error("Missing type.");
+      if (!name) throw new Error("Missing name.");
+      if (!vec.isFinite3(offset)) throw new Error("Invalid offset (expected [forward,right,up] numbers).");
+      let origin = null;
+      let rot = null;
+      let surfaceNormal = null;
+      if (anchor === "selection" || anchor === "editor_camera") {
+        const ctx = unwrapUnrealMcpResult(await types.sendUnrealMcpTcpCommand({ type: "get_editor_context", params: {}, timeoutMs }));
+        unrealEditorSupervisor.noteUnrealReachable();
+        if (anchor === "selection") {
+          const sel = Array.isArray(ctx?.selection) ? ctx.selection : [];
+          if (sel.length === 0) throw new Error("No selected actors in Unreal Editor. Select an actor and retry.");
+          const first = sel[0];
+          origin = Array.isArray(first?.location) ? first.location : null;
+          rot = Array.isArray(first?.rotation) ? first.rotation : null;
+        } else {
+          const cam = ctx?.viewportCamera;
+          if (!cam || cam === null) throw new Error("No active viewport camera. Click the viewport and retry.");
+          origin = Array.isArray(cam?.location) ? cam.location : null;
+          rot = Array.isArray(cam?.rotation) ? cam.rotation : null;
+        }
+      } else if (anchor === "player_camera") {
+        const pc = unwrapUnrealMcpResult(await types.sendUnrealMcpTcpCommand({ type: "get_player_context", params: {}, timeoutMs }));
+        unrealEditorSupervisor.noteUnrealReachable();
+        if (!pc?.isPlaying) throw new Error("PIE is not running. Start PIE and retry (or use editor_camera/selection anchors).");
+        const cam = pc?.camera;
+        origin = Array.isArray(cam?.location) ? cam.location : null;
+        rot = Array.isArray(cam?.rotation) ? cam.rotation : null;
+      } else if (anchor === "actor") {
+        const actorName = String(args.actorName || "").trim();
+        if (!actorName) throw new Error('anchor="actor" requires actorName.');
+        const t = unwrapUnrealMcpResult(await types.sendUnrealMcpTcpCommand({ type: "get_actor_transform", params: { name: actorName, source: "editor" }, timeoutMs }));
+        unrealEditorSupervisor.noteUnrealReachable();
+        origin = Array.isArray(t?.location) ? t.location : null;
+        rot = Array.isArray(t?.rotation) ? t.rotation : null;
+      } else if (anchor === "hit_result") {
+        const hit = unwrapUnrealMcpResult(await types.sendUnrealMcpTcpCommand({ type: "raycast_from_camera", params: { source: raySource, maxDistance }, timeoutMs }));
+        unrealEditorSupervisor.noteUnrealReachable();
+        if (!hit?.hit) throw new Error("Raycast did not hit anything.");
+        origin = Array.isArray(hit?.location) ? hit.location : null;
+        surfaceNormal = Array.isArray(hit?.normal) ? hit.normal : null;
+        const ctxRot = raySource === "pie" ? unwrapUnrealMcpResult(await types.sendUnrealMcpTcpCommand({ type: "get_player_context", params: {}, timeoutMs }))?.camera?.rotation : unwrapUnrealMcpResult(await types.sendUnrealMcpTcpCommand({ type: "get_editor_context", params: {}, timeoutMs }))?.viewportCamera?.rotation;
+        rot = Array.isArray(ctxRot) ? ctxRot : [0, 0, 0];
+      } else {
+        throw new Error(`Unknown anchor: ${anchor}`);
+      }
+      if (!vec.isFinite3(origin)) throw new Error("Anchor origin is missing or invalid.");
+      if (!rot || !vec.isFinite3(rot)) throw new Error("Anchor rotation is missing or invalid.");
+      const basis = forwardRightUpFromRotator(rot);
+      let target = vec.add(origin, vec.add(vec.mul(basis.forward, offset[0]), vec.add(vec.mul(basis.right, offset[1]), vec.mul(basis.up, offset[2]))));
+      let finalNormal = surfaceNormal;
+      if (dropToGround) {
+        const start = vec.add(target, [0, 0, 1e4]);
+        const down = unwrapUnrealMcpResult(await types.sendUnrealMcpTcpCommand({ type: "raycast_down", params: { source: "editor", startLocation: start, maxDistance: 2e5 }, timeoutMs }));
+        unrealEditorSupervisor.noteUnrealReachable();
+        if (down?.hit && Array.isArray(down?.location)) {
+          target = down.location;
+          if (Array.isArray(down?.normal)) finalNormal = down.normal;
+        } else {
+          throw new Error("dropToGround=true but raycast_down did not hit anything.");
+        }
+      }
+      let outRot = rot;
+      if (alignToSurface && vec.isFinite3(finalNormal)) {
+        const up = vec.norm(finalNormal);
+        let fwd = basis.forward;
+        fwd = vec.sub(fwd, vec.mul(up, vec.dot(fwd, up)));
+        if (vec.len(fwd) <= 1e-4) {
+          fwd = vec.cross([0, 1, 0], up);
+        }
+        fwd = vec.norm(fwd);
+        const right = vec.norm(vec.cross(up, fwd));
+        const fixedFwd = vec.norm(vec.cross(right, up));
+        outRot = rotatorFromBasis({ forward: fixedFwd, right, up });
+      }
+      const spawned = await types.sendUnrealMcpTcpCommand({
+        type: "spawn_actor",
+        params: { type, name, location: target, rotation: outRot },
+        timeoutMs: Math.max(timeoutMs, 1e4)
+      });
+      unrealEditorSupervisor.noteUnrealReachable();
+      const payload = {
+        anchor,
+        origin,
+        offset,
+        location: target,
+        rotation: outRot,
+        ...finalNormal ? { normal: finalNormal } : {},
+        spawned
+      };
+      return {
+        content: [
+          { type: "text", text: "Spawned actor relative to context." },
+          { type: "text", text: JSON.stringify(payload, null, 2) }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          { type: "text", text: "Failed to spawn actor relative to context." },
+          { type: "text", text: error instanceof Error ? error.message : String(error) }
+        ],
+        isError: true
+      };
+    }
+  }));
+  mcp.registerTool("unreal_mcp_get_actors_in_level", {
+    title: "Unreal Actors In Level (UnrealMCP)",
+    description: "List all actors in the current Unreal Editor level via the UnrealMCP engine plugin. Requires Unreal Editor running with the UnrealMCP plugin enabled.",
+    inputSchema: {
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_mcp_get_actors_in_level", args, async () => {
     const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
     try {
       const response = await types.sendUnrealMcpTcpCommand({ type: "get_actors_in_level", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       const actors = Array.isArray(response?.actors) ? response.actors : Array.isArray(response?.result?.actors) ? response.result.actors : null;
       if (!actors) {
         return {
@@ -7914,8 +9859,10 @@ ${String(st.stdout || "").trim()}`
     }
   }, async (args) => runWithMcpToolCard("unreal_mcp_get_play_in_editor_status", args, async () => {
     const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
     try {
       const response = await types.sendUnrealMcpTcpCommand({ type: "get_play_in_editor_status", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       return {
         content: [
           { type: "text", text: "Fetched Play-In-Editor status." },
@@ -7942,6 +9889,7 @@ ${String(st.stdout || "").trim()}`
     }
   }, async (args) => runWithMcpToolCard("unreal_mcp_editor_health", args, async () => {
     const timeoutMs = args.timeoutMs ?? 1500;
+    unrealEditorSupervisor.noteUnrealActivity();
     const classify = (message) => {
       const m = message.toLowerCase();
       if (m.includes("econnrefused")) return { state: "offline", hint: "UnrealMCP TCP port is not accepting connections (Unreal Editor likely closed/crashed or plugin not running)." };
@@ -7951,10 +9899,12 @@ ${String(st.stdout || "").trim()}`
     };
     try {
       const ping = await types.sendUnrealMcpTcpCommand({ type: "ping", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       const pluginInfo = await getUnrealMcpPluginInfoBestEffort(timeoutMs);
       let pieStatus = null;
       try {
         pieStatus = await types.sendUnrealMcpTcpCommand({ type: "get_play_in_editor_status", params: {}, timeoutMs });
+        unrealEditorSupervisor.noteUnrealReachable();
       } catch {
         pieStatus = null;
       }
@@ -7994,8 +9944,10 @@ ${String(st.stdout || "").trim()}`
     }
   }, async (args) => runWithMcpToolCard("unreal_mcp_play_in_editor", args, async () => {
     const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
     try {
       const response = await types.sendUnrealMcpTcpCommand({ type: "play_in_editor", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       return {
         content: [
           { type: "text", text: "Requested Play In Editor (PIE) in active viewport." },
@@ -8022,8 +9974,10 @@ ${String(st.stdout || "").trim()}`
     }
   }, async (args) => runWithMcpToolCard("unreal_mcp_play_in_editor_windowed", args, async () => {
     const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
     try {
       const response = await types.sendUnrealMcpTcpCommand({ type: "play_in_editor_windowed", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       return {
         content: [
           { type: "text", text: "Requested Play In Editor (PIE) in a new editor window." },
@@ -8051,8 +10005,10 @@ ${String(st.stdout || "").trim()}`
     }
   }, async (args) => runWithMcpToolCard("unreal_mcp_stop_play_in_editor", args, async () => {
     const timeoutMs = args.timeoutMs ?? 5e3;
+    unrealEditorSupervisor.noteUnrealActivity();
     try {
       const response = await types.sendUnrealMcpTcpCommand({ type: "stop_play_in_editor", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       return {
         content: [
           { type: "text", text: "Requested Stop Play In Editor (PIE)." },
@@ -8070,6 +10026,48 @@ ${String(st.stdout || "").trim()}`
       };
     }
   }));
+  mcp.registerTool("unreal_smoke_test", {
+    title: "Unreal Smoke Test (PIE + Screenshot Validation)",
+    description: 'Evidence-first "did it run?": ensures PIE is stopped, starts PIE in a new window, waits briefly, captures a validation screenshot to Saved/Screenshots/Flockbay, stops PIE, then uploads the screenshot to the current session.',
+    inputSchema: {
+      uprojectPath: z.z.string().describe("Absolute path to the .uproject file (used to locate Saved/Screenshots/Flockbay for evidence upload)."),
+      stabilizeMs: z.z.number().int().positive().optional().describe("Time to wait before taking screenshot (default 1500)."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms for each step (default 30000)."),
+      stopIfPlaying: z.z.boolean().optional().describe("If PIE is already running, stop it first (default true).")
+    }
+  }, async (args) => runWithMcpToolCard("unreal_smoke_test", args, async () => {
+    const uprojectPath = typeof args?.uprojectPath === "string" ? String(args.uprojectPath).trim() : "";
+    const stabilizeMs = typeof args?.stabilizeMs === "number" ? args.stabilizeMs : void 0;
+    const timeoutMs = typeof args?.timeoutMs === "number" ? args.timeoutMs : void 0;
+    const stopIfPlaying = typeof args?.stopIfPlaying === "boolean" ? args.stopIfPlaying : void 0;
+    if (!uprojectPath || !uprojectPath.toLowerCase().endsWith(".uproject") || !path.isAbsolute(uprojectPath)) {
+      return {
+        content: [{ type: "text", text: `Invalid uprojectPath (must be an absolute path to *.uproject): ${String(uprojectPath)}` }],
+        isError: true
+      };
+    }
+    if (!fs.existsSync(uprojectPath)) {
+      return { content: [{ type: "text", text: `uprojectPath not found: ${uprojectPath}` }], isError: true };
+    }
+    unrealEditorSupervisor.noteUnrealActivity();
+    const result = await runUnrealSmokeTest({ uprojectPath, stabilizeMs, timeoutMs, stopIfPlaying });
+    let viewsPayload = [];
+    if (result.screenshotPath && typeof result.screenshotPath === "string" && fs.existsSync(result.screenshotPath)) {
+      const uploaded = await uploadScreenshotViewsForSession({
+        sessionId: client.sessionId,
+        token: client.getAuthToken(),
+        views: [{ id: "smoke_test", path: result.screenshotPath }]
+      });
+      viewsPayload = uploaded.map((u) => ({ ...u, id: u.id || "smoke_test" }));
+    }
+    const payload = { ...result, ...viewsPayload.length ? { views: viewsPayload } : {} };
+    const content = [
+      { type: "text", text: result.ok ? "Smoke test succeeded." : "Smoke test failed." },
+      ...result.screenshotPath ? [{ type: "text", text: `Screenshot: ${result.screenshotPath}` }] : [],
+      { type: "text", text: JSON.stringify(payload, null, 2) }
+    ];
+    return { content, ...viewsPayload.length ? { views: viewsPayload } : {}, isError: !result.ok };
+  }));
   mcp.registerTool("unreal_mechanic_run", {
     title: "Unreal Mechanic Builder (Dash MVP)",
     description: "Create a project-safe mechanic test map (Parallel mode) and prove it works with Flockbay screenshot evidence. V1 supports dash only.",
@@ -8231,13 +10229,48 @@ Fix: ${res.hint}` : "";
       "read_images",
       "unreal_headless_screenshot",
       "unreal_latest_screenshots",
+      "unreal_editor_launch",
+      "unreal_build_project",
       "unreal_mcp_command",
+      "unreal_mcp_list_capabilities",
+      "unreal_mcp_get_command_schema",
+      "unreal_mcp_search_blueprint_functions",
+      "unreal_mcp_resolve_blueprint_function",
+      "unreal_mcp_search_assets",
+      "unreal_mcp_get_asset_info",
+      "unreal_mcp_list_asset_packs",
+      "unreal_mcp_place_asset",
+      "unreal_mcp_get_editor_context",
+      "unreal_mcp_get_player_context",
+      "unreal_mcp_raycast_from_camera",
+      "unreal_mcp_raycast_down",
+      "unreal_mcp_get_actor_transform",
+      "unreal_mcp_get_actor_bounds",
+      "unreal_mcp_create_landscape",
+      "unreal_mcp_map_check",
+      "unreal_mcp_compile_blueprints_all",
+      "unreal_mcp_save_all",
+      "unreal_place_asset_relative",
+      "unreal_spawn_actor_relative",
       "unreal_mcp_get_actors_in_level",
+      "unreal_mcp_get_play_in_editor_status",
+      "unreal_mcp_editor_health",
+      "unreal_mcp_play_in_editor",
+      "unreal_mcp_play_in_editor_windowed",
+      "unreal_mcp_stop_play_in_editor",
+      "unreal_smoke_test",
       "unreal_fast_preview",
       "unreal_mechanic_run"
     ],
+    unreal: {
+      onIssue: (handler2) => {
+        unrealIssueEmitter.on("issue", handler2);
+        return () => unrealIssueEmitter.off("issue", handler2);
+      }
+    },
     stop: () => {
       types.logger.debug("[flockbayMCP] Stopping server");
+      unrealEditorSupervisor.stop();
       mcp.close();
       server.close();
     }
@@ -8462,8 +10495,20 @@ async function runClaude(credentials, options = {}) {
     lifecycleStateSince: Date.now(),
     flavor: "claude"
   };
-  const response = await api.getOrCreateSession({ tag: sessionTag, metadata, state });
-  types.logger.debug(`Session created: ${response.id}`);
+  const response = options.sessionId ? await api.getSessionById(options.sessionId) : await api.getOrCreateSession({ tag: sessionTag, metadata, state });
+  types.logger.debug(`${options.sessionId ? "Session attached" : "Session created"}: ${response.id}`);
+  const session = api.sessionSyncClient(response);
+  if (options.sessionId) {
+    session.updateMetadata((currentMetadata) => ({
+      ...currentMetadata,
+      ...metadata,
+      // Preserve user-facing fields set by other clients.
+      name: currentMetadata?.name,
+      summary: currentMetadata?.summary
+    }));
+  }
+  await session.connectAndWait(15e3);
+  session.keepAlive(false, options.startingMode === "remote" ? "remote" : "local");
   try {
     types.logger.debug(`[START] Reporting session ${response.id} to daemon`);
     const result = await notifyDaemonSessionStarted(response.id, metadata);
@@ -8478,7 +10523,7 @@ async function runClaude(credentials, options = {}) {
   extractSDKMetadataAsync(async (sdkMetadata) => {
     types.logger.debug("[start] SDK metadata extracted, updating session:", sdkMetadata);
     try {
-      api.sessionSyncClient(response).updateMetadata((currentMetadata) => ({
+      session.updateMetadata((currentMetadata) => ({
         ...currentMetadata,
         tools: sdkMetadata.tools,
         slashCommands: sdkMetadata.slashCommands
@@ -8488,7 +10533,6 @@ async function runClaude(credentials, options = {}) {
       types.logger.debug("[start] Failed to update session metadata:", error);
     }
   });
-  const session = api.sessionSyncClient(response);
   const elicitationHub = new ElicitationHub();
   const flockbayServer = await startFlockbayServer(session, { elicitationHub });
   types.logger.debug(`[START] Flockbay MCP server started at ${flockbayServer.url}`);
@@ -8840,20 +10884,45 @@ async function handleAuthCommand(args) {
     return;
   }
   switch (subcommand) {
-    case "login":
-      await handleAuthLogin(args.slice(1));
-      break;
-    case "logout":
-      await handleAuthLogout();
-      break;
-    case "show-backup":
-    case "show_backup":
-    case "backup":
-      await handleAuthShowBackup();
-      break;
-    case "status":
-      await handleAuthStatus();
-      break;
+    case "login": {
+      const force = args.includes("--force") || args.includes("-f");
+      if (force) {
+        try {
+          await stopDaemon();
+        } catch {
+        }
+        await types.clearCredentials();
+        if (args.includes("--clear-machine-id")) {
+          await types.clearMachineId();
+        }
+      }
+      await loginWithClerkAndPairMachine();
+      return;
+    }
+    case "logout": {
+      try {
+        await stopDaemon();
+      } catch {
+      }
+      await types.clearCredentials();
+      await types.clearMachineId();
+      console.log(chalk.green("\u2713 Logged out (profile reset)"));
+      return;
+    }
+    case "status": {
+      const auth = await types.readCredentials();
+      const settings = await types.readSettings();
+      const daemon = await types.readDaemonState();
+      console.log(chalk.bold("\nAuthentication Status\n"));
+      console.log(chalk.gray(`Profile:  ${types.configuration.profile}`));
+      console.log(chalk.gray(`Server:   ${types.configuration.serverUrl}`));
+      console.log(chalk.gray(`Web app:  ${types.configuration.webappUrl}`));
+      console.log(chalk.gray(`Machine:  ${String(settings?.machineId || "missing")}`));
+      console.log(chalk.gray(`Workspace:${auth?.orgId ? ` ${auth.orgId}` : " missing"}`));
+      console.log(chalk.gray(`Auth:     ${auth?.machineToken ? "paired" : "not paired"}`));
+      console.log(chalk.gray(`Daemon:   ${daemon?.pid ? `pid=${daemon.pid} port=${daemon.httpPort}` : "not running"}`));
+      return;
+    }
     default:
       console.error(chalk.red(`Unknown auth subcommand: ${subcommand}`));
       showAuthHelp();
@@ -8862,186 +10931,14 @@ async function handleAuthCommand(args) {
 }
 function showAuthHelp() {
   console.log(`
-${chalk.bold("flockbay auth")} - Authentication management
+${chalk.bold("flockbay auth")} - Authentication management (Clerk-based)
 
 ${chalk.bold("Usage:")}
-  flockbay auth login [--force] [--mobile]    Authenticate with Flockbay
-  flockbay auth logout             Remove authentication and machine data
-  flockbay auth status             Show authentication status
-  flockbay auth show-backup        Display backup key for mobile/web clients
-  flockbay auth help               Show this help message
-
-${chalk.bold("Options:")}
-  --force    Clear credentials, machine ID, and stop daemon before re-auth
-  --mobile   Authenticate by scanning a QR code (advanced)
-  --web      Authenticate via browser login (default)
-`);
-}
-async function handleAuthLogin(args) {
-  const forceAuth = args.includes("--force") || args.includes("-f");
-  const quiet = args.includes("--quiet") || args.includes("--no-summary");
-  const preferMobile = args.includes("--mobile");
-  const preferWeb = args.includes("--web");
-  if (preferMobile && preferWeb) {
-    console.error(chalk.red("Choose only one authentication method: --mobile or --web"));
-    process.exit(1);
-  }
-  const authMethod = preferMobile ? "mobile" : "web";
-  if (forceAuth) {
-    if (!quiet) {
-      console.log(chalk.yellow("Force authentication requested."));
-      console.log(chalk.gray("This will:"));
-      console.log(chalk.gray("  \u2022 Clear existing credentials"));
-      console.log(chalk.gray("  \u2022 Clear machine ID"));
-      console.log(chalk.gray("  \u2022 Stop daemon if running"));
-      console.log(chalk.gray("  \u2022 Re-authenticate and register machine\n"));
-    }
-    try {
-      types.logger.debug("Stopping daemon for force auth...");
-      await stopDaemon();
-      if (!quiet) console.log(chalk.gray("\u2713 Stopped daemon"));
-    } catch (error) {
-      types.logger.debug("Daemon was not running or failed to stop:", error);
-    }
-    await types.clearCredentials();
-    if (!quiet) console.log(chalk.gray("\u2713 Cleared credentials"));
-    await types.clearMachineId();
-    if (!quiet) console.log(chalk.gray("\u2713 Cleared machine ID"));
-    if (!quiet) console.log("");
-  }
-  if (!forceAuth) {
-    const existingCreds = await types.readCredentials();
-    const settings = await types.readSettings();
-    if (existingCreds && settings?.machineId) {
-      if (!quiet) {
-        console.log(chalk.green("\u2713 Already authenticated"));
-        console.log(chalk.gray(`  Machine ID: ${settings.machineId}`));
-        console.log(chalk.gray(`  Host: ${os.hostname()}`));
-        console.log(chalk.gray(`  Use 'flockbay auth login --force' to re-authenticate`));
-      }
-      return;
-    } else if (existingCreds && !settings?.machineId) {
-      if (!quiet) {
-        console.log(chalk.yellow("\u26A0\uFE0F  Credentials exist but machine ID is missing"));
-        console.log(chalk.gray("  This can happen if --auth flag was used previously"));
-        console.log(chalk.gray("  Fixing by setting up machine...\n"));
-      }
-    }
-  }
-  try {
-    const result = await authAndSetupMachineIfNeeded({ authMethod });
-    if (!quiet) {
-      console.log(chalk.green("\n\u2713 Authentication successful"));
-      console.log(chalk.gray(`  Machine ID: ${result.machineId}`));
-      console.log(chalk.gray(`  Server: ${types.configuration.serverUrl}`));
-      console.log(chalk.gray(`  Web app: ${types.configuration.webappUrl}`));
-      console.log(
-        chalk.gray(
-          `
-Next: run ${chalk.bold("flockbay start")} to start the daemon (this is what makes your computer appear as connected in the app).`
-        )
-      );
-    }
-  } catch (error) {
-    console.error(chalk.red("Authentication failed:"), error instanceof Error ? error.message : "Unknown error");
-    process.exit(1);
-  }
-}
-async function handleAuthLogout() {
-  const dataDir = types.configuration.flockbayHomeDir;
-  const credentials = await types.readCredentials();
-  if (!credentials) {
-    console.log(chalk.yellow("Not currently authenticated"));
-    return;
-  }
-  console.log(chalk.blue("This will log you out of Flockbay"));
-  console.log(chalk.yellow("\u26A0\uFE0F  You will need to re-authenticate to use Flockbay again"));
-  const rl = node_readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-  const answer = await new Promise((resolve) => {
-    rl.question(chalk.yellow("Are you sure you want to log out? (y/N): "), resolve);
-  });
-  rl.close();
-  if (answer.toLowerCase() === "y" || answer.toLowerCase() === "yes") {
-    try {
-      try {
-        await stopDaemon();
-        console.log(chalk.gray("Stopped daemon"));
-      } catch (err) {
-        console.error("[auth logout] Failed to stop daemon during logout", err);
-        console.log(chalk.yellow("Warning: failed to stop daemon (continuing logout)."));
-      }
-      if (fs.existsSync(dataDir)) {
-        fs.rmSync(dataDir, { recursive: true, force: true });
-      }
-      console.log(chalk.green("\u2713 Successfully logged out"));
-      console.log(chalk.gray('  Run "flockbay auth login" to authenticate again'));
-    } catch (error) {
-      throw new Error(`Failed to logout: ${error instanceof Error ? error.message : "Unknown error"}`);
-    }
-  } else {
-    console.log(chalk.blue("Logout cancelled"));
-  }
-}
-async function handleAuthShowBackup() {
-  const accessKeyPath = types.configuration.privateKeyFile;
-  if (!fs.existsSync(accessKeyPath)) {
-    console.log(chalk.red("\u2717 Not authenticated"));
-    console.log(chalk.gray('  Run "flockbay auth login" to authenticate'));
-    process.exit(1);
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(fs.readFileSync(accessKeyPath, "utf8"));
-  } catch {
-    console.error(chalk.red("Backup key unavailable: failed to parse key file."));
-    process.exit(1);
-  }
-  const machineKeyB64 = parsed?.encryption?.machineKey;
-  if (!machineKeyB64 || typeof machineKeyB64 !== "string") {
-    console.error(chalk.red("Backup key unavailable: encryption.machineKey missing in key file."));
-    process.exit(1);
-  }
-  const buf = Buffer.from(machineKeyB64, "base64");
-  const key = buf.toString("base64url");
-  process.stdout.write(`${key}
+  flockbay auth login [--force] [--clear-machine-id]   Sign in and pair this machine to a workspace
+  flockbay auth logout                                 Clear local auth + machine id for this profile
+  flockbay auth status                                 Show current status
 `);
 }
-async function handleAuthStatus() {
-  const credentials = await types.readCredentials();
-  const settings = await types.readSettings();
-  console.log(chalk.bold("\nAuthentication Status\n"));
-  if (!credentials) {
-    console.log(chalk.red("\u2717 Not authenticated"));
-    console.log(chalk.gray('  Run "flockbay auth login" to authenticate'));
-    return;
-  }
-  console.log(chalk.green("\u2713 Authenticated"));
-  const tokenPreview = credentials.token.substring(0, 30) + "...";
-  console.log(chalk.gray(`  Token: ${tokenPreview}`));
-  if (settings?.machineId) {
-    console.log(chalk.green("\u2713 Machine registered"));
-    console.log(chalk.gray(`  Machine ID: ${settings.machineId}`));
-    console.log(chalk.gray(`  Host: ${os.hostname()}`));
-  } else {
-    console.log(chalk.yellow("\u26A0\uFE0F  Machine not registered"));
-    console.log(chalk.gray('  Run "flockbay auth login --force" to fix this'));
-  }
-  console.log(chalk.gray(`
-  Data directory: ${types.configuration.flockbayHomeDir}`));
-  try {
-    const running = await checkIfDaemonRunningAndCleanupStaleState();
-    if (running) {
-      console.log(chalk.green("\u2713 Daemon running"));
-    } else {
-      console.log(chalk.gray("\u2717 Daemon not running"));
-    }
-  } catch {
-    console.log(chalk.gray("\u2717 Daemon not running"));
-  }
-}
 
 const CLIENT_ID$2 = "app_EMoamEEZ73f0CkXaXp7hrann";
 const AUTH_BASE_URL = "https://auth.openai.com";
@@ -9667,6 +11564,15 @@ function looksLikeMachineAuthMismatch(logTail) {
   const hasMachinesEndpoint = /\/v1\/machines\b/i.test(t);
   return has401 && hasMachinesEndpoint;
 }
+function looksLikeServerUnreachable(logTail) {
+  const t = String(logTail || "");
+  if (!t) return null;
+  const codeMatch = t.match(/\b(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ECONNRESET|ETIMEDOUT)\b/) || t.match(/connect\s+(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ECONNRESET|ETIMEDOUT)\b/i);
+  const code = codeMatch?.[1] || codeMatch?.[0] || null;
+  if (!code) return null;
+  const url = t.match(/"url"\s*:\s*"([^"]+)"/)?.[1] ?? null;
+  return { code: String(code), url };
+}
 async function promptYesNo(question, { defaultYes }) {
   const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
   if (!isInteractive) return false;
@@ -9689,10 +11595,135 @@ async function reauthForCurrentServerKeepingMachineId() {
   } catch {
   }
   await types.clearCredentials();
-  await authAndSetupMachineIfNeeded();
+  await loginWithClerkAndPairMachine();
+}
+function openUrlBestEffort(url) {
+  const u = String(url || "").trim();
+  if (!u) return;
+  if (process.env.FLOCKBAY_NO_OPEN === "1") return;
+  const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!isInteractive) return;
+  try {
+    if (process.platform === "darwin") {
+      const p2 = node_child_process.spawn("open", [u], { detached: true, stdio: "ignore" });
+      p2.unref();
+      return;
+    }
+    if (process.platform === "win32") {
+      const p2 = node_child_process.spawn("cmd", ["/c", "start", "", u], { detached: true, stdio: "ignore" });
+      p2.unref();
+      return;
+    }
+    const p = node_child_process.spawn("xdg-open", [u], { detached: true, stdio: "ignore" });
+    p.unref();
+  } catch {
+  }
+}
+async function fetchDaemonStatus() {
+  const state = await types.readDaemonState().catch(() => null);
+  if (!state?.httpPort || !state?.pid) return null;
+  try {
+    process.kill(state.pid, 0);
+  } catch {
+    return null;
+  }
+  try {
+    const res = await fetch(`http://127.0.0.1:${state.httpPort}/status`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "{}",
+      signal: AbortSignal.timeout(1500)
+    });
+    if (!res.ok) return null;
+    return await res.json().catch(() => null);
+  } catch {
+    return null;
+  }
+}
+async function waitForDaemonConnected(timeoutMs) {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  while (Date.now() < deadline) {
+    const status = await fetchDaemonStatus();
+    const connected = Boolean(status?.connection?.connected);
+    if (connected) return status;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return fetchDaemonStatus();
 }
 async function startDaemonDetachedOrExit(opts) {
-  const child = spawnFlockbayCLI(["daemon", "start-sync"], {
+  const alreadyRunning = await checkIfDaemonRunningAndCleanupStaleState().catch(() => false);
+  if (alreadyRunning) {
+    const versionMatches = await isDaemonRunningCurrentCliVersion().catch(() => true);
+    if (!versionMatches) {
+      await stopDaemon();
+    } else {
+      const status = await waitForDaemonConnected(5e3);
+      const connected = Boolean(status?.connection?.connected);
+      const lastUpsertStatus = Number.isFinite(Number(status?.connection?.lastHttpUpsertStatus)) ? Number(status.connection.lastHttpUpsertStatus) : null;
+      const lastConnectError = typeof status?.connection?.lastConnectError === "string" ? status.connection.lastConnectError : "";
+      if (connected) {
+        const auth = await types.readCredentials().catch(() => null);
+        const settings = await types.readSettings().catch(() => null);
+        const daemon = await types.readDaemonState().catch(() => null);
+        const desiredOrgId = auth?.orgId ? String(auth.orgId).trim() : "";
+        const desiredMachineId = settings?.machineId ? String(settings.machineId).trim() : "";
+        const daemonOrgId = typeof status?.orgId === "string" ? status.orgId.trim() : "";
+        const daemonMachineId = typeof status?.machineId === "string" ? status.machineId.trim() : "";
+        const daemonServerUrl = typeof status?.serverUrl === "string" ? status.serverUrl.trim() : "";
+        const desiredServerUrl = String(types.configuration.serverUrl || "").trim();
+        const orgMismatch = desiredOrgId && daemonOrgId && desiredOrgId !== daemonOrgId;
+        const machineMismatch = desiredMachineId && daemonMachineId && desiredMachineId !== daemonMachineId;
+        const serverMismatch = desiredServerUrl && daemonServerUrl && desiredServerUrl !== daemonServerUrl;
+        if ((orgMismatch || machineMismatch || serverMismatch) && !opts?.restartAttempted) {
+          console.error("");
+          console.error(chalk.yellow("Daemon is running with different settings than the current CLI profile."));
+          if (serverMismatch) console.error(chalk.gray(`Daemon server: ${daemonServerUrl || "unknown"}`));
+          if (desiredServerUrl) console.error(chalk.gray(`CLI server:   ${desiredServerUrl}`));
+          if (orgMismatch) console.error(chalk.gray(`Daemon org:   ${daemonOrgId || "unknown"}`));
+          if (desiredOrgId) console.error(chalk.gray(`CLI org:     ${desiredOrgId}`));
+          if (machineMismatch) console.error(chalk.gray(`Daemon machine: ${daemonMachineId || "unknown"}`));
+          if (desiredMachineId) console.error(chalk.gray(`CLI machine:    ${desiredMachineId}`));
+          console.error(chalk.gray("Restarting daemon to apply current login/pairing..."));
+          await stopDaemon();
+          await startDaemonDetachedOrExit({ ...opts, restartAttempted: true });
+          return;
+        }
+        console.log(chalk.bold("\nFlockbay ready\n"));
+        console.log(chalk.gray(`Profile:  ${types.configuration.profile}`));
+        console.log(chalk.gray(`Server:   ${types.configuration.serverUrl}`));
+        console.log(chalk.gray(`Web app:  ${types.configuration.webappUrl}`));
+        console.log(chalk.gray(`Machine:  ${String(settings?.machineId || "missing")}`));
+        console.log(chalk.gray(`Workspace:${auth?.orgId ? ` ${auth.orgId}` : " missing"}`));
+        console.log(chalk.gray(`Daemon:   ${daemon?.pid ? `pid=${daemon.pid} port=${daemon.httpPort}` : "not running"}`));
+        console.log("");
+        openUrlBestEffort(types.configuration.webappUrl);
+        process.exit(0);
+      }
+      const authMismatch = lastUpsertStatus === 401 || /unauthorized/i.test(lastConnectError);
+      if (authMismatch && !opts?.reauthAttempted) {
+        console.error("");
+        console.error(chalk.yellow("Your saved CLI token was rejected by the server (401/unauthorized)."));
+        console.error(chalk.gray("This is common in local dev if the backend store was reset/rebuilt."));
+        console.error("");
+        const shouldReauth = await promptYesNo("Re-authenticate now and retry?", { defaultYes: true });
+        if (shouldReauth) {
+          await reauthForCurrentServerKeepingMachineId();
+          await startDaemonDetachedOrExit({ reauthAttempted: true });
+          return;
+        }
+        process.exit(1);
+      }
+      console.error("");
+      console.error(chalk.red("Daemon is running but not connected to the server."));
+      if (typeof status?.connection?.lastHttpUpsertError === "string" && status.connection.lastHttpUpsertError.trim()) {
+        console.error(chalk.gray(`Last upsert error: ${status.connection.lastHttpUpsertError.trim()}`));
+      }
+      if (lastConnectError) console.error(chalk.gray(`Last connect error: ${lastConnectError}`));
+      console.error(chalk.gray("Tip: if the backend is restarting, wait a moment and re-run `flockbay start`."));
+      process.exit(1);
+    }
+  }
+  const child = spawnFlockbayCLI(["daemon", "start-sync", "--profile", types.configuration.profile], {
     detached: true,
     stdio: "ignore",
     env: process.env
@@ -9707,7 +11738,28 @@ async function startDaemonDetachedOrExit(opts) {
     await new Promise((resolve) => setTimeout(resolve, 100));
   }
   if (started) {
-    console.log("Daemon started successfully");
+    const status = await waitForDaemonConnected(5e3);
+    if (!Boolean(status?.connection?.connected)) {
+      const lastUpsertError = typeof status?.connection?.lastHttpUpsertError === "string" ? status.connection.lastHttpUpsertError.trim() : "";
+      const lastConnectError = typeof status?.connection?.lastConnectError === "string" ? status.connection.lastConnectError.trim() : "";
+      console.error(chalk.red("Daemon started, but failed to connect to the server."));
+      if (lastUpsertError) console.error(chalk.gray(`Last upsert error: ${lastUpsertError}`));
+      if (lastConnectError) console.error(chalk.gray(`Last connect error: ${lastConnectError}`));
+      console.error(chalk.gray("Tip: if the backend is restarting, wait a moment and re-run `flockbay start`."));
+      process.exit(1);
+    }
+    const auth = await types.readCredentials().catch(() => null);
+    const settings = await types.readSettings().catch(() => null);
+    const daemon = await types.readDaemonState().catch(() => null);
+    console.log(chalk.bold("\nFlockbay ready\n"));
+    console.log(chalk.gray(`Profile:  ${types.configuration.profile}`));
+    console.log(chalk.gray(`Server:   ${types.configuration.serverUrl}`));
+    console.log(chalk.gray(`Web app:  ${types.configuration.webappUrl}`));
+    console.log(chalk.gray(`Machine:  ${String(settings?.machineId || "missing")}`));
+    console.log(chalk.gray(`Workspace:${auth?.orgId ? ` ${auth.orgId}` : " missing"}`));
+    console.log(chalk.gray(`Daemon:   ${daemon?.pid ? `pid=${daemon.pid} port=${daemon.httpPort}` : "not running"}`));
+    console.log("");
+    openUrlBestEffort(types.configuration.webappUrl);
     process.exit(0);
   } else {
     const latest = await types.getLatestDaemonLog();
@@ -9728,6 +11780,19 @@ async function startDaemonDetachedOrExit(opts) {
       console.error(chalk.gray("Fix: run `flockbay start` to re-authenticate and restart the daemon."));
       process.exit(1);
     }
+    const unreachable = looksLikeServerUnreachable(logTail);
+    if (unreachable) {
+      console.error("");
+      console.error(chalk.red(`Cannot reach server while starting daemon (${unreachable.code}).`));
+      console.error(chalk.gray(`Server: ${types.configuration.serverUrl}`));
+      if (unreachable.url) console.error(chalk.gray(`Failed request: ${unreachable.url}`));
+      if (/^https?:\/\/(127\.0\.0\.1|localhost)\b/i.test(types.configuration.serverUrl)) {
+        console.error("");
+        console.error(chalk.gray("Local dev fix: start the backend first, then re-run `flockbay start`:"));
+        console.error(chalk.gray("  cd backend && npm run dev"));
+      }
+      process.exit(1);
+    }
     console.error("Failed to start daemon");
     console.error("Tip: run `flockbay auth status` to confirm you are logged in.");
     process.exit(1);
@@ -9738,10 +11803,10 @@ function showStartHelp() {
 ${chalk.bold("flockbay start")} - One-command setup
 
 ${chalk.bold("Usage:")}
-  flockbay start [--engine-root <path>]    Authenticate and start the daemon
+  flockbay start [--engine-root <path>] [--profile <name>]    Ensure login + daemon running
 
 ${chalk.bold("Options:")}
-  (start always forces a login; same as \`flockbay auth login --force\`)
+  --profile <name>         CLI profile (isolates server/workspace/machine state)
   --engine-root <path>    Unreal Engine install folder (UE_5.5\u2013UE_5.7)
   --skip-unreal            Skip Unreal bridge install
 `);
@@ -9753,6 +11818,10 @@ function readArgValue(args, key) {
   if (!value || value.startsWith("-")) return null;
   return value;
 }
+async function authAndSetupMachineIfNeeded() {
+  const { auth, machineId } = await ensureMachineAuthOrLogin();
+  return { credentials: auth, machineId };
+}
 (async () => {
   const invokedCwd = process.env.FLOCKBAY_INVOKED_CWD;
   if (invokedCwd?.trim()) {
@@ -9773,6 +11842,9 @@ function readArgValue(args, key) {
     args = args.slice(1);
     subcommand = args[0];
   }
+  if (subcommand === "setup") {
+    subcommand = "start";
+  }
   if (!args.includes("--version")) ;
   if (subcommand === "doctor") {
     if (args[1] === "clean") {
@@ -9796,6 +11868,43 @@ function readArgValue(args, key) {
       process.exit(1);
     }
     return;
+  } else if (subcommand === "login") {
+    try {
+      await loginWithClerkAndPairMachine();
+    } catch (error) {
+      console.error(chalk.red("Error:"), error instanceof Error ? error.message : "Unknown error");
+      if (process.env.DEBUG) console.error(error);
+      process.exit(1);
+    }
+    return;
+  } else if (subcommand === "status") {
+    const auth = await types.readCredentials();
+    const settings = await types.readSettings();
+    const daemon = await types.readDaemonState();
+    console.log(chalk.bold("\nFlockbay Status\n"));
+    console.log(chalk.gray(`Profile: ${types.configuration.profile}`));
+    console.log(chalk.gray(`Server:   ${types.configuration.serverUrl}`));
+    console.log(chalk.gray(`Web app:  ${types.configuration.webappUrl}`));
+    console.log(chalk.gray(`Machine:  ${String(settings?.machineId || "missing")}`));
+    console.log(chalk.gray(`Workspace:${auth?.orgId ? ` ${auth.orgId}` : " missing"}`));
+    console.log(chalk.gray(`Auth:     ${auth?.machineToken ? "paired" : "not paired"}`));
+    console.log(chalk.gray(`Daemon:   ${daemon?.pid ? `pid=${daemon.pid} port=${daemon.httpPort}` : "not running"}`));
+    process.exit(0);
+  } else if (subcommand === "reset") {
+    const force = args.includes("--force");
+    if (!force) {
+      console.error(chalk.red("Refusing to reset without --force"));
+      console.error(chalk.gray("This clears local auth + machine binding for this profile."));
+      process.exit(1);
+    }
+    try {
+      await stopDaemon();
+    } catch {
+    }
+    await types.clearCredentials();
+    await types.clearMachineId();
+    console.log("Reset complete");
+    process.exit(0);
   } else if (subcommand === "connect") {
     try {
       await handleConnectCommand(args.slice(1));
@@ -9807,22 +11916,14 @@ function readArgValue(args, key) {
       process.exit(1);
     }
     return;
-  } else if (subcommand === "start" || subcommand === "setup") {
-    if (subcommand === "setup") {
-      console.log(chalk.yellow("Note: `flockbay setup` was renamed to `flockbay start`."));
-      console.log(chalk.gray("Running `flockbay start`...\n"));
-    }
+  } else if (subcommand === "start") {
     const startArgs = args.slice(1);
     if (startArgs.includes("--help") || startArgs.includes("-h") || startArgs.includes("help")) {
       showStartHelp();
       return;
     }
     try {
-      try {
-        await checkIfDaemonRunningAndCleanupStaleState();
-        await stopDaemon();
-      } catch {
-      }
+      await ensureMachineAuthOrLogin();
       const skipUnreal = startArgs.includes("--skip-unreal");
       if (!skipUnreal) {
         const engineRoot = readArgValue(startArgs, "--engine-root") || (process.env.UE_ENGINE_ROOT || "").trim() || (process.env.ENGINE_ROOT || "").trim() || null;
@@ -9844,7 +11945,6 @@ ${engineRoot}`, {
           }
         }
       }
-      await handleAuthCommand(["login", "--force", "--quiet"]);
       await startDaemonDetachedOrExit();
     } catch (error) {
       console.error(chalk.red("Error:"), error instanceof Error ? error.message : "Unknown error");
@@ -9857,17 +11957,20 @@ ${engineRoot}`, {
   } else if (subcommand === "codex") {
     try {
       await chdirToNearestUprojectRootIfPresent();
-      const { runCodex } = await Promise.resolve().then(function () { return require('./runCodex-D3eT-TvB.cjs'); });
+      const { runCodex } = await Promise.resolve().then(function () { return require('./runCodex-DuCGwO2K.cjs'); });
       let startedBy = void 0;
+      let sessionId = void 0;
       for (let i = 1; i < args.length; i++) {
         if (args[i] === "--started-by") {
           startedBy = args[++i];
+        } else if (args[i] === "--flockbay-session-id") {
+          sessionId = args[++i];
         }
       }
       const {
         credentials
       } = await authAndSetupMachineIfNeeded();
-      await runCodex({ credentials, startedBy });
+      await runCodex({ credentials, startedBy, sessionId });
     } catch (error) {
       console.error(chalk.red("Error:"), error instanceof Error ? error.message : "Unknown error");
       if (process.env.DEBUG) {
@@ -9949,11 +12052,14 @@ ${engineRoot}`, {
     }
     try {
       await chdirToNearestUprojectRootIfPresent();
-      const { runGemini } = await Promise.resolve().then(function () { return require('./runGemini-CBxZp6I7.cjs'); });
+      const { runGemini } = await Promise.resolve().then(function () { return require('./runGemini-B25LZ4Cw.cjs'); });
       let startedBy = void 0;
+      let sessionId = void 0;
       for (let i = 1; i < args.length; i++) {
         if (args[i] === "--started-by") {
           startedBy = args[++i];
+        } else if (args[i] === "--flockbay-session-id") {
+          sessionId = args[++i];
         }
       }
       const {
@@ -9970,19 +12076,7 @@ ${engineRoot}`, {
         daemonProcess.unref();
         await new Promise((resolve) => setTimeout(resolve, 200));
       }
-      await runGemini({ credentials, startedBy });
-    } catch (error) {
-      console.error(chalk.red("Error:"), error instanceof Error ? error.message : "Unknown error");
-      if (process.env.DEBUG) {
-        console.error(error);
-      }
-      process.exit(1);
-    }
-    return;
-  } else if (subcommand === "logout") {
-    console.log(chalk.yellow('Note: "logout" is deprecated. Use "flockbay auth logout" instead.\n'));
-    try {
-      await handleAuthCommand(["logout"]);
+      await runGemini({ credentials, startedBy, sessionId });
     } catch (error) {
       console.error(chalk.red("Error:"), error instanceof Error ? error.message : "Unknown error");
       if (process.env.DEBUG) {
@@ -10111,6 +12205,8 @@ ${chalk.bold("To clean up runaway processes:")} Use ${chalk.cyan("flockbay docto
         unknownArgs.push("--dangerously-skip-permissions");
       } else if (arg === "--started-by") {
         options.startedBy = args[++i];
+      } else if (arg === "--flockbay-session-id") {
+        options.sessionId = args[++i];
       } else if (arg === "--claude-env") {
         const envArg = args[++i];
         if (envArg && envArg.includes("=")) {
@@ -10295,6 +12391,7 @@ exports.applyCoordinationSideEffectsFromMcpToolResult = applyCoordinationSideEff
 exports.autoFinalizeCoordinationWorkItem = autoFinalizeCoordinationWorkItem;
 exports.buildProjectCapsule = buildProjectCapsule;
 exports.consumeToolQuota = consumeToolQuota;
+exports.detectScreenshotsForGate = detectScreenshotsForGate;
 exports.detectUnrealProject = detectUnrealProject;
 exports.extractUserImagesMarker = extractUserImagesMarker;
 exports.formatQuotaDeniedReason = formatQuotaDeniedReason;