flockbay 0.10.15 → 0.10.16

package/dist/{index-CUp3juDS.mjs → index-DtmFQzXY.mjs}

@@ -1,33 +1,30 @@
 import{createRequire as _pkgrollCR}from"node:module";const require=_pkgrollCR(import.meta.url);import chalk from 'chalk';
 import os, { homedir } from 'node:os';
-import { randomUUID, randomBytes } from 'node:crypto';
-import { l as logger, p as projectPath, d as backoff, e as delay, R as RawJSONLinesSchema, f as AsyncLock, c as configuration, g as readDaemonState, h as clearDaemonState, b as packageJson, r as readSettings, i as readCredentials, j as encodeBase64, u as updateSettings, k as encodeBase64Url, m as decodeBase64, w as writeCredentialsDataKey, n as unrealMcpPythonDir, o as acquireDaemonLock, q as writeDaemonState, A as ApiClient, s as releaseDaemonLock, t as sendUnrealMcpTcpCommand, v as clearCredentials, x as clearMachineId, y as installUnrealMcpPluginToEngine, z as getLatestDaemonLog } from './types-DGd6ea2Z.mjs';
+import { randomUUID, createCipheriv, randomBytes } from 'node:crypto';
+import { l as logger, p as projectPath, d as backoff, e as delay, R as RawJSONLinesSchema, c as configuration, f as readDaemonState, g as clearDaemonState, b as packageJson, r as readSettings, h as readCredentials, u as updateSettings, w as writeCredentials, i as unrealMcpPythonDir, j as acquireDaemonLock, k as writeDaemonState, m as ApiMachineClient, n as releaseDaemonLock, s as sendUnrealMcpTcpCommand, A as ApiClient, o as clearCredentials, q as clearMachineId, t as installUnrealMcpPluginToEngine, v as getLatestDaemonLog } from './types-CwzNqYEx.mjs';
 import { spawn, execFileSync, execSync } from 'node:child_process';
 import path, { resolve, join, dirname } from 'node:path';
 import { createInterface } from 'node:readline';
 import * as fs from 'node:fs';
-import fs__default, { existsSync, readFileSync, mkdirSync, readdirSync, accessSync, constants, statSync, createReadStream, writeFileSync, unlinkSync, rmSync } from 'node:fs';
+import fs__default, { existsSync, readFileSync, mkdirSync, readdirSync, accessSync, constants, statSync, createReadStream, writeFileSync, unlinkSync } from 'node:fs';
 import process$1 from 'node:process';
-import fs$1, { readFile, access as access$1, stat, mkdir, readdir } from 'node:fs/promises';
+import fs$1, { readFile, access as access$1, mkdir, stat, readdir } from 'node:fs/promises';
 import fs$2, { watch, access } from 'fs/promises';
 import { useStdout, useInput, Box, Text, render } from 'ink';
 import React, { useState, useRef, useEffect, useCallback } from 'react';
 import { fileURLToPath } from 'node:url';
 import axios from 'axios';
-import 'node:events';
+import { EventEmitter } from 'node:events';
 import 'socket.io-client';
-import tweetnacl from 'tweetnacl';
 import { spawn as spawn$1, execSync as execSync$1, exec } from 'child_process';
 import { createHash, randomBytes as randomBytes$1 } from 'crypto';
 import { join as join$1, basename } from 'path';
 import os$1 from 'os';
 import 'node:net';
-import 'expo-server-sdk';
 import { readFileSync as readFileSync$1, existsSync as existsSync$1, writeFileSync as writeFileSync$1, chmodSync, unlinkSync as unlinkSync$1 } from 'fs';
 import psList from 'ps-list';
 import spawn$2 from 'cross-spawn';
 import * as tmp from 'tmp';
-import qrcode from 'qrcode-terminal';
 import open from 'open';
 import fastify from 'fastify';
 import { z } from 'zod';
@@ -35,6 +32,7 @@ import { validatorCompiler, serializerCompiler } from 'fastify-type-provider-zod
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { createServer } from 'node:http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import 'tweetnacl';
 import { createServer as createServer$1 } from 'http';
 import { promisify } from 'util';
 
@@ -276,27 +274,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
 
@@ -315,9 +354,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
 
@@ -836,7 +876,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();
@@ -884,8 +924,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);
@@ -1891,6 +1929,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;
@@ -2001,6 +2172,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({
@@ -2075,6 +2301,17 @@ async function claudeRemote(opts) {
       if (message.type === "result") {
         updateThinking(false);
         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) {
           logger.debug("[claudeRemote] Compaction completed");
           if (opts.onCompletionEvent) {
@@ -2089,14 +2326,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)) {
               logger.debug("[claudeRemote] Tool aborted, exiting claudeRemote");
               return;
@@ -2643,11 +2885,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"
@@ -3058,6 +3303,40 @@ 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;
@@ -3249,7 +3528,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 ?? {})
@@ -3391,7 +3670,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(
@@ -4247,7 +4526,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" },
@@ -4341,6 +4622,7 @@ async function stopDaemon() {
       try {
         await stopDaemonHttp();
         await waitForProcessDeath(state.pid, 2e3);
+        await cleanupDaemonState();
         logger.debug("Daemon stopped gracefully via HTTP");
         return;
       } catch (error) {
@@ -4635,37 +4917,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 = encodeBase64(publicKey, "base64url");
-  const server = encodeURIComponent(configuration.serverUrl);
-  const shouldAutoLogout = (() => {
-    try {
-      const serverUrl = new URL(configuration.serverUrl);
-      const webUrl = new URL(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 `${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";
@@ -4683,217 +4934,78 @@ async function openBrowser(url) {
   }
 }
 
-async function doAuth(options) {
-  console.clear();
-  const authMethod = options?.method === "mobile" ? "mobile" : "web";
-  const secret = new Uint8Array(randomBytes(32));
-  const keypair = tweetnacl.box.keyPair.fromSecretKey(secret);
-  try {
-    console.log(`[AUTH DEBUG] Sending auth request to: ${configuration.serverUrl}/v1/auth/request`);
-    console.log(`[AUTH DEBUG] Public key: ${encodeBase64(keypair.publicKey).substring(0, 20)}...`);
-    await axios.post(`${configuration.serverUrl}/v1/auth/request`, {
-      publicKey: 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() {
+  logger.debug("[AUTH] Starting Clerk-based CLI login + machine pairing");
+  const settings = await updateSettings(async (s) => {
+    const machineId2 = s.machineId || randomUUID();
+    const serverUrl2 = s.serverUrl || configuration.serverUrl;
+    const webappUrl = s.webappUrl || configuration.webappUrl;
+    return { ...s, machineId: machineId2, serverUrl: serverUrl2, webappUrl };
+  });
+  const serverUrl = 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?" + 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(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 ${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(`${configuration.serverUrl}/v1/auth/request`, { publicKey: encodeBase64(keypair.publicKey) });
-        if (response.data.state === "authorized") {
-          let token = response.data.token;
-          let r = 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: randomBytes(32),
-              token
-            };
-            await 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: ${configuration.profile}`));
+  console.log(chalk.gray(`Server:  ${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 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 delay(1e3);
+      const auth = { machineToken, orgId, createdAtMs: Date.now() };
+      await 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) {
-  logger.debug("[AUTH] Starting auth and machine setup...");
-  const allowAuthFlow = options?.allowAuthFlow !== false;
-  const authMethod = options?.authMethod === "mobile" ? "mobile" : "web";
-  let credentials = await readCredentials();
-  if (!credentials) {
-    if (!allowAuthFlow) {
-      throw new Error('Not authenticated. Run "flockbay auth login" first.');
-    }
-    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 {
-    logger.debug("[AUTH] Using existing credentials");
+async function ensureMachineAuthOrLogin() {
+  const existing = await readCredentials();
+  const settings = await 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(`${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(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 readSettings();
-  const preferredMachineId = !existingSettings.machineId ? await findMatchingExistingMachineId() : null;
-  const settings = await updateSettings(async (s) => {
-    const machineId = s.machineId || preferredMachineId || randomUUID();
-    const serverUrl = s.serverUrl || configuration.serverUrl;
-    const webappUrl = s.webappUrl || configuration.webappUrl;
-    return { ...s, machineId, serverUrl, webappUrl };
-  });
-  logger.debug(`[AUTH] Machine ID: ${settings.machineId}`);
-  return { credentials, machineId: settings.machineId };
+  const auth = await loginWithClerkAndPairMachine();
+  const updated = await readSettings();
+  const mid = String(updated?.machineId || "").trim();
+  if (!mid) throw new Error("Missing machineId after login.");
+  return { auth, machineId: mid };
 }
 
 function resolveTsxImportArgs(projectRoot) {
@@ -4973,6 +5085,7 @@ Error: ${message}` };
 
 function startDaemonControlServer({
   getChildren,
+  getStatus,
   stopSession,
   spawnSession,
   requestShutdown,
@@ -5028,6 +5141,15 @@ function startDaemonControlServer({
         }))
       };
     });
+    typed.post("/status", {
+      schema: {
+        response: {
+          200: z.any()
+        }
+      }
+    }, async () => {
+      return getStatus();
+    });
     typed.post("/stop-session", {
       schema: {
         body: z.object({
@@ -5167,6 +5289,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$1.access(p);
@@ -5237,15 +5379,23 @@ const initialMachineMetadata = {
   flockbayLibDir: projectPath()
 };
 async function startDaemon() {
+  let startupCompleted = false;
+  let startupForceExitTimer = null;
   let requestShutdown;
   let resolvesWhenShutdownRequested = new Promise((resolve) => {
     requestShutdown = (source, errorMessage) => {
       logger.debug(`[DAEMON RUN] Requesting shutdown (source: ${source}, errorMessage: ${errorMessage})`);
-      setTimeout(async () => {
-        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 () => {
+          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 });
     };
   });
@@ -5299,7 +5449,7 @@ async function startDaemon() {
     if (caffeinateStarted) {
       logger.debug("[DAEMON RUN] Sleep prevention enabled");
     }
-    const { credentials, machineId } = await authAndSetupMachineIfNeeded({ allowAuthFlow: false });
+    const { auth: credentials, machineId } = await ensureMachineAuthOrLogin();
     logger.debug("[DAEMON RUN] Auth and machine setup complete");
     const shouldStartUnrealMcp = String(process.env.FLOCKBAY_UNREAL_MCP_ENABLED || "").trim() === "1";
     if (shouldStartUnrealMcp) {
@@ -5312,10 +5462,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$2.readdir(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$2.stat(join$1(configuration.logsDir, file));
+            const mtimeMs = Number(st.mtimeMs || 0);
+            if (!best || mtimeMs > best.mtimeMs) best = { file, mtimeMs };
+          } catch {
+          }
+        }
+        return best ? join$1(configuration.logsDir, best.file) : null;
+      } catch {
+        return null;
+      }
+    };
+    const readLogTail = async (path, maxBytes) => {
+      try {
+        const st = await fs$2.stat(path);
+        const size = Number(st.size || 0);
+        const offset = Math.max(0, size - maxBytes);
+        const handle = await fs$2.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) => {
       logger.debugLargeJson(`[DAEMON RUN] Session reported`, sessionMetadata);
       const pid = sessionMetadata.hostPid;
@@ -5329,6 +5524,9 @@ async function startDaemon() {
       if (existingSession && existingSession.startedBy === "daemon") {
         existingSession.serverSessionId = sessionId;
         existingSession.serverSessionMetadataFromLocalWebhook = sessionMetadata;
+        if (existingSession.spawnOptions) {
+          existingSession.spawnOptions = { ...existingSession.spawnOptions, sessionId };
+        }
         logger.debug(`[DAEMON RUN] Updated daemon-spawned session ${sessionId} with metadata`);
         const awaiter = pidToAwaiter.get(pid);
         if (awaiter) {
@@ -5367,16 +5565,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) {
@@ -5397,7 +5586,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 ?? {})
@@ -5598,11 +5787,16 @@ Fix: restart session creation and re-select the project.`
         }
         const args = [
           agentCommand,
+          "--profile",
+          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,
@@ -5645,24 +5839,30 @@ Fix: restart session creation and re-select the project.`
           };
         }
         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) => {
           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) => {
           logger.debug(`[DAEMON RUN] Child process error:`, error);
           if (sessionProcess.pid) {
-            onChildExited(sessionProcess.pid);
+            onChildExited(sessionProcess.pid, { code: null, signal: null });
           }
         });
         logger.debug(`[DAEMON RUN] Waiting for session webhook for PID ${sessionProcess.pid}`);
@@ -5685,17 +5885,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 ${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 ${configuration.logsDir})`}`
+              });
+            })();
           };
           sessionProcess.once("exit", onEarlyExit);
           sessionProcess.once("error", onEarlyError);
@@ -5745,8 +5953,13 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
     };
     const stopSession = (sessionId) => {
       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");
@@ -5762,20 +5975,144 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
               logger.debug(`[DAEMON RUN] Failed to kill external session PID ${pid}:`, error);
             }
           }
-          pidToTrackedSession.delete(pid);
-          logger.debug(`[DAEMON RUN] Removed session ${sessionId} from tracking`);
+          logger.debug(`[DAEMON RUN] Stop requested for session ${sessionId}; waiting for exit to remove tracking`);
           return true;
         }
       }
       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)) {
+        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) {
+        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") {
+        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;
+      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)) {
+          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") {
+              logger.debug(`[DAEMON RUN] Auto-restart succeeded for session ${sessionId}`);
+              sessionAutoRestart.delete(sessionId);
+              return;
+            }
+            logger.debug(
+              `[DAEMON RUN] Auto-restart failed for session ${sessionId} (type=${result.type}): ${result.type === "error" ? result.errorMessage : "needs-user-approval"}`
+            );
+          } catch (err) {
+            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);
       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)) {
+        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))
+      })) {
+        logger.debug(`[DAEMON RUN] Not auto-restarting session ${sessionId} (clean exit)`);
+        sessionAutoRestart.delete(sessionId);
+        return;
+      }
+      if (!tracked.spawnOptions) {
+        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;
+        logger.debug(
+          `[DAEMON RUN] Session runtime log tail for ${sessionId} (pid=${pid}, log=${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: configuration.profile,
+        serverUrl: configuration.serverUrl,
+        webappUrl: configuration.webappUrl,
+        orgId: credentials?.orgId || null,
+        machineId,
+        daemonPid: process.pid,
+        daemonHttpPort: controlPort,
+        startedWithCliVersion: 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"),
@@ -5797,93 +6134,89 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
       httpPort: controlPort,
       startedAt: Date.now()
     };
-    const apiClient = await 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;
-      }
-    }
-    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 ApiMachineClient(credentials.machineToken, machine);
     apiMachine.setRPCHandlers({
       spawnSession,
       stopSession,
       requestShutdown: () => requestShutdown("flockbay-app")
     });
-    apiMachine.connect();
+    try {
+      apiMachine.connect();
+    } catch (err) {
+      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) {
-        logger.debug(`[DAEMON RUN] Health check started at ${(/* @__PURE__ */ new Date()).toLocaleString()}`);
-      }
-      for (const [pid, _] of pidToTrackedSession.entries()) {
+      try {
+        if (process.env.DEBUG) {
+          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) {
+            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(readFileSync$1(join$1(projectPath(), "package.json"), "utf-8")).version;
+          if (projectVersion !== configuration.currentCliVersion) {
+            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) {
+              logger.debug("[DAEMON RUN] Failed to spawn new daemon, this can happen during integration tests", error);
+            }
+            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) {
-          logger.debug(`[DAEMON RUN] Removing stale session with PID ${pid} (process no longer exists)`);
-          pidToTrackedSession.delete(pid);
+          logger.debug("[DAEMON RUN] Failed to check CLI version during health check", error);
+        }
+        const daemonState = await readDaemonState();
+        if (daemonState && daemonState.pid !== process.pid) {
+          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(readFileSync$1(join$1(projectPath(), "package.json"), "utf-8")).version;
-      if (projectVersion !== configuration.currentCliVersion) {
-        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: packageJson.version,
+            lastHeartbeat: (/* @__PURE__ */ new Date()).toLocaleString(),
+            daemonLogPath: fileState.daemonLogPath
+          };
+          writeDaemonState(updatedState);
+          if (process.env.DEBUG) {
+            logger.debug(`[DAEMON RUN] Health check completed at ${updatedState.lastHeartbeat}`);
+          }
         } catch (error) {
-          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);
-        }
-        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 readDaemonState();
-      if (daemonState && daemonState.pid !== process.pid) {
-        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: packageJson.version,
-          lastHeartbeat: (/* @__PURE__ */ new Date()).toLocaleString(),
-          daemonLogPath: fileState.daemonLogPath
-        };
-        writeDaemonState(updatedState);
-        if (process.env.DEBUG) {
-          logger.debug(`[DAEMON RUN] Health check completed at ${updatedState.lastHeartbeat}`);
+          logger.debug("[DAEMON RUN] Failed to write heartbeat", error);
         }
-      } catch (error) {
-        logger.debug("[DAEMON RUN] Failed to write heartbeat", error);
+      } finally {
+        heartbeatRunning = false;
       }
-      heartbeatRunning = false;
     }, heartbeatIntervalMs);
     const cleanupAndShutdown = async (source, errorMessage) => {
       logger.debug(`[DAEMON RUN] Starting proper cleanup (source: ${source}, errorMessage: ${errorMessage})...`);
@@ -5892,13 +6225,15 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
         clearInterval(restartOnStaleVersionAndHeartbeat);
         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());
@@ -5949,7 +6284,7 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
       } else {
         logger.debug("[DAEMON RUN] Preserving session processes across daemon shutdown");
       }
-      apiMachine.shutdown();
+      apiMachine?.shutdown();
       try {
         unrealMcpChild?.kill();
       } catch {
@@ -5964,7 +6299,12 @@ Fix: restart the daemon and try again (macOS: \`flockbay daemon stop\` then \`fl
       process.exit(0);
     };
     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) {
     logger.debug("[DAEMON RUN][FATAL] Failed somewhere unexpectedly - exiting with code 1", error);
@@ -6007,12 +6347,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__default.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__default.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__default.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__default.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" ? spawn("cmd.exe", ["/c", script, ...buildArgs], { stdio: ["ignore", "pipe", "pipe"] }) : 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 mkdir(screenshotDir, { recursive: true });
+  const screenshotPath = path.join(screenshotDir, `Flockbay_smoke_test_${stampForFilename()}.png`);
+  let started = false;
+  let stopped = false;
+  try {
+    const status = await 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 sendUnrealMcpTcpCommand({ type: "stop_play_in_editor", params: {}, timeoutMs: Math.min(timeoutMs, 1e4) });
+    }
+    const playRes = await 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 sendUnrealMcpTcpCommand({ type: "take_screenshot", params: { filepath: screenshotPath }, timeoutMs: Math.min(timeoutMs, 2e4) });
+    await 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);
@@ -6229,12 +6816,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(randomBytes(size));
+}
+function encryptWithDataKey(data, dataKey) {
+  const nonce = getRandomBytes(12);
+  const cipher = 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 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 (!existsSync(engineRoot)) return false;
+  if (!existsSync(path.join(engineRoot, "Engine"))) return false;
+  const buildVersion = path.join(engineRoot, "Engine", "Build", "Build.version");
+  if (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 && 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 (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 = spawn(args.cmd, args.cmdArgs, { stdio: ["ignore", "pipe", "pipe"], cwd: args.cwd, env: args.env });
@@ -6280,7 +7027,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
   });
@@ -6316,11 +7065,14 @@ async function startFlockbayServer(client, options) {
   const handler = async (title) => {
     logger.debug("[flockbayMCP] Changing title to:", title);
     try {
-      client.sendClaudeSessionMessage({
-        type: "summary",
-        summary: title,
-        leafUuid: 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) };
@@ -6349,7 +7101,7 @@ async function startFlockbayServer(client, options) {
     const res = await fetch(`${configuration.serverUrl.replace(/\/+$/, "")}${pathname}`, {
       method: "POST",
       headers: {
-        Authorization: `Bearer ${client.getAuthToken()}`,
+        Authorization: `Machine ${client.getAuthToken()}`,
         "Content-Type": "application/json"
       },
       body: JSON.stringify(body ?? {})
@@ -6374,6 +7126,166 @@ async function startFlockbayServer(client, options) {
     const meta = client?.metadata;
     return String(meta?.path || "").trim() || process.cwd();
   };
+  const unrealIssueEmitter = new 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) {
+          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 = 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 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 (!existsSync(exe)) throw new Error(`Unreal Editor binary not found: ${exe}`);
+      const child = 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",
@@ -7081,7 +7993,7 @@ ${String(st.stdout || "").trim()}`
       const url = `${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) {
@@ -7106,7 +8018,7 @@ ${String(st.stdout || "").trim()}`
       const url = `${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) {
@@ -7662,6 +8574,7 @@ ${String(st.stdout || "").trim()}`
         }
         return {
           content,
+          views: viewsPayload,
           isError: false
         };
       } catch (error) {
@@ -7676,8 +8589,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.string().describe("Absolute path to the .uproject file."),
       limit: z.number().int().positive().optional().describe("Max number of screenshots to return (default 12)."),
@@ -7762,6 +8675,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) {
@@ -7797,6 +8711,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)";
@@ -7804,10 +8719,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.string().describe("Absolute path to the .uproject file."),
+      engineRoot: z.string().optional().describe("Optional Unreal Engine install root. Defaults to ENGINE_ROOT / UE_ENGINE_ROOT, or inferred from EngineAssociation when possible."),
+      extraArgs: z.array(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 (!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.string().describe("Absolute path to the .uproject file."),
+      engineRoot: z.string().optional().describe("Optional Unreal Engine install root. Defaults to ENGINE_ROOT / UE_ENGINE_ROOT, or inferred from EngineAssociation when possible."),
+      configuration: z.enum(["Debug", "DebugGame", "Development", "Shipping"]).optional().describe("Build configuration (default Development)."),
+      target: z.enum(["Editor", "Game"]).optional().describe("Build target (default Editor)."),
+      timeoutMs: z.number().int().positive().optional().describe("Timeout in ms (default 20m)."),
+      issuesLimit: 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 (!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.",
@@ -7820,10 +8851,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 sendUnrealMcpTcpCommand({ type, params, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       return {
         content: [
           { type: "text", text: `UnrealMCP command ok: ${type}` },
@@ -7846,16 +8879,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.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 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.string().optional().describe('Command type to fetch schema for (e.g. "create_blueprint").'),
+      timeoutMs: 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 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.string().describe('Substring to search for (e.g. "MakeVector", "SetRelativeLocation").'),
+      target: z.string().optional().describe('Optional target class constraint (e.g. "KismetMathLibrary").'),
+      limit: z.number().int().positive().optional().describe("Max results (default 25)."),
       timeoutMs: 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 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.string().describe('Function name to resolve (e.g. "MakeVector").'),
+      target: z.string().optional().describe("Optional target class constraint."),
+      timeoutMs: 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 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.string().optional().describe("Fuzzy search string (name/path)."),
+      class: z.union([z.string(), z.array(z.string())]).optional().describe('Optional asset class filter (e.g. "StaticMesh", "Blueprint", "Material").'),
+      root: z.string().optional().describe('Root path to search (default "/Game/").'),
+      limit: z.number().int().positive().optional().describe("Max results (default 25, max 200)."),
+      timeoutMs: 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 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.string().describe('Unreal asset object path (e.g. "/Game/MyPack/MyMesh.MyMesh").'),
+      includeDependencies: z.boolean().optional().describe("Include package dependencies (default false)."),
+      timeoutMs: 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 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.number().int().positive().optional().describe("Max number of packs (default 200)."),
+      timeoutMs: 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 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.string().describe('Unreal asset object path (e.g. "/Game/MyPack/MyMesh.MyMesh").'),
+      name: z.string().optional().describe("Optional actor name (default: derived from asset name)."),
+      location: z.array(z.number()).length(3).optional().describe("Spawn location [X,Y,Z] in cm."),
+      rotation: z.array(z.number()).length(3).optional().describe("Spawn rotation [Pitch,Yaw,Roll] in degrees."),
+      scale: z.array(z.number()).length(3).optional().describe("Spawn scale [X,Y,Z]."),
+      timeoutMs: 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 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.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 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.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 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.enum(["editor", "pie"]).optional().describe("Camera source (default editor)."),
+      maxDistance: z.number().positive().optional().describe("Max distance in cm (default 10000)."),
+      ignoreActors: z.array(z.string()).optional().describe("Actor names/labels to ignore (best-effort)."),
+      timeoutMs: 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 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.enum(["editor", "pie"]).optional().describe("World source (default editor)."),
+      startLocation: z.array(z.number()).length(3).describe("Start location [X,Y,Z] in cm."),
+      maxDistance: z.number().positive().optional().describe("Max distance in cm (default 100000)."),
+      timeoutMs: 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 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.string().describe("Actor name or label."),
+      source: z.enum(["editor", "pie"]).optional().describe("World source (default editor)."),
+      timeoutMs: 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 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.string().describe("Actor name or label."),
+      source: z.enum(["editor", "pie"]).optional().describe("World source (default editor)."),
+      timeoutMs: 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 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.string().describe("New landscape actor name (must be unique)."),
+      componentCountX: z.number().int().positive().optional().describe("Number of components in X (default 8)."),
+      componentCountY: z.number().int().positive().optional().describe("Number of components in Y (default 8)."),
+      sectionsPerComponent: z.number().int().optional().describe("Sections per component (1 or 2, default 1)."),
+      quadsPerSection: z.number().int().positive().optional().describe("Quads per section (default 63)."),
+      location: z.array(z.number()).length(3).optional().describe("Center location [X,Y,Z] in cm (default [0,0,0])."),
+      rotation: z.array(z.number()).length(3).optional().describe("Rotation [Pitch,Yaw,Roll] in degrees (default [0,0,0])."),
+      scale: z.array(z.number()).length(3).optional().describe("Scale [X,Y,Z] (default [100,100,100])."),
+      materialPath: z.string().optional().describe('Optional landscape material object path (e.g. "/Game/\u2026/M_Landscape.M_Landscape").'),
+      timeoutMs: 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 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.boolean().optional().describe("Include warnings in the issues list (default true)."),
+      limit: z.number().int().positive().optional().describe("Max number of issues to return (default 200, max 1000)."),
+      timeoutMs: 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 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.array(z.string()).optional().describe('Root content paths to search (default ["/Game"]).'),
+      includeWarnings: z.boolean().optional().describe("Include warnings in the per-blueprint messages list (default true)."),
+      limit: z.number().int().positive().optional().describe("Max number of blueprints to compile (default 500, max 10000)."),
+      timeoutMs: z.number().int().positive().optional().describe("Socket timeout in ms (default 60000).")
+    }
+  }, 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 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.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 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.string().describe('Unreal asset object path (e.g. "/Game/MyPack/MyMesh.MyMesh").'),
+      name: z.string().optional().describe("Optional actor name (default: derived from asset name)."),
+      anchor: z.enum(["selection", "editor_camera", "player", "player_camera", "hit_result", "actor"]).describe("Reference anchor for placement."),
+      actorName: z.string().optional().describe('When anchor="actor", the actor name/label to anchor to.'),
+      offset: z.array(z.number()).length(3).optional().describe("Offset in anchor local axes [forwardCm, rightCm, upCm] (default [200,0,0])."),
+      alignToSurface: z.boolean().optional().describe("When using hit_result or drop-to-ground hits, align actor up to hit normal (default false)."),
+      dropToGround: z.boolean().optional().describe("After computing target location, raycast down and snap to the hit location (default false)."),
+      raySource: z.enum(["editor", "pie"]).optional().describe('When anchor="hit_result", which camera to raycast from (default editor).'),
+      maxDistance: z.number().positive().optional().describe("Raycast max distance in cm (default 10000)."),
+      timeoutMs: 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 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 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 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 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 sendUnrealMcpTcpCommand({ type: "get_player_context", params: {}, timeoutMs }))?.camera?.rotation : unwrapUnrealMcpResult(await 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 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 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.string().describe('Actor class/type (e.g. "PointLight", "CameraActor", "StaticMeshActor").'),
+      name: z.string().describe("Actor name."),
+      anchor: z.enum(["selection", "editor_camera", "player", "player_camera", "hit_result", "actor"]).describe("Reference anchor for placement."),
+      actorName: z.string().optional().describe('When anchor="actor", the actor name/label to anchor to.'),
+      offset: z.array(z.number()).length(3).optional().describe("Offset in anchor local axes [forwardCm, rightCm, upCm] (default [200,0,0])."),
+      alignToSurface: z.boolean().optional().describe("When using hit_result or drop-to-ground hits, align actor up to hit normal (default false)."),
+      dropToGround: z.boolean().optional().describe("After computing target location, raycast down and snap to the hit location (default false)."),
+      raySource: z.enum(["editor", "pie"]).optional().describe('When anchor="hit_result", which camera to raycast from (default editor).'),
+      maxDistance: z.number().positive().optional().describe("Raycast max distance in cm (default 10000)."),
+      timeoutMs: 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 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 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 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 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 sendUnrealMcpTcpCommand({ type: "get_player_context", params: {}, timeoutMs }))?.camera?.rotation : unwrapUnrealMcpResult(await 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 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 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.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 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 {
@@ -7892,8 +9837,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 sendUnrealMcpTcpCommand({ type: "get_play_in_editor_status", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       return {
         content: [
           { type: "text", text: "Fetched Play-In-Editor status." },
@@ -7920,6 +9867,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)." };
@@ -7929,10 +9877,12 @@ ${String(st.stdout || "").trim()}`
     };
     try {
       const ping = await sendUnrealMcpTcpCommand({ type: "ping", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       const pluginInfo = await getUnrealMcpPluginInfoBestEffort(timeoutMs);
       let pieStatus = null;
       try {
         pieStatus = await sendUnrealMcpTcpCommand({ type: "get_play_in_editor_status", params: {}, timeoutMs });
+        unrealEditorSupervisor.noteUnrealReachable();
       } catch {
         pieStatus = null;
       }
@@ -7972,8 +9922,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 sendUnrealMcpTcpCommand({ type: "play_in_editor", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       return {
         content: [
           { type: "text", text: "Requested Play In Editor (PIE) in active viewport." },
@@ -8000,8 +9952,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 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." },
@@ -8029,8 +9983,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 sendUnrealMcpTcpCommand({ type: "stop_play_in_editor", params: {}, timeoutMs });
+      unrealEditorSupervisor.noteUnrealReachable();
       return {
         content: [
           { type: "text", text: "Requested Stop Play In Editor (PIE)." },
@@ -8048,6 +10004,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.string().describe("Absolute path to the .uproject file (used to locate Saved/Screenshots/Flockbay for evidence upload)."),
+      stabilizeMs: z.number().int().positive().optional().describe("Time to wait before taking screenshot (default 1500)."),
+      timeoutMs: z.number().int().positive().optional().describe("Socket timeout in ms for each step (default 30000)."),
+      stopIfPlaying: 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 (!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" && 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.",
@@ -8209,13 +10207,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: () => {
       logger.debug("[flockbayMCP] Stopping server");
+      unrealEditorSupervisor.stop();
       mcp.close();
       server.close();
     }
@@ -8440,8 +10473,20 @@ async function runClaude(credentials, options = {}) {
     lifecycleStateSince: Date.now(),
     flavor: "claude"
   };
-  const response = await api.getOrCreateSession({ tag: sessionTag, metadata, state });
-  logger.debug(`Session created: ${response.id}`);
+  const response = options.sessionId ? await api.getSessionById(options.sessionId) : await api.getOrCreateSession({ tag: sessionTag, metadata, state });
+  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 {
     logger.debug(`[START] Reporting session ${response.id} to daemon`);
     const result = await notifyDaemonSessionStarted(response.id, metadata);
@@ -8456,7 +10501,7 @@ async function runClaude(credentials, options = {}) {
   extractSDKMetadataAsync(async (sdkMetadata) => {
     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
@@ -8466,7 +10511,6 @@ async function runClaude(credentials, options = {}) {
       logger.debug("[start] Failed to update session metadata:", error);
     }
   });
-  const session = api.sessionSyncClient(response);
   const elicitationHub = new ElicitationHub();
   const flockbayServer = await startFlockbayServer(session, { elicitationHub });
   logger.debug(`[START] Flockbay MCP server started at ${flockbayServer.url}`);
@@ -8818,20 +10862,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 clearCredentials();
+        if (args.includes("--clear-machine-id")) {
+          await clearMachineId();
+        }
+      }
+      await loginWithClerkAndPairMachine();
+      return;
+    }
+    case "logout": {
+      try {
+        await stopDaemon();
+      } catch {
+      }
+      await clearCredentials();
+      await clearMachineId();
+      console.log(chalk.green("\u2713 Logged out (profile reset)"));
+      return;
+    }
+    case "status": {
+      const auth = await readCredentials();
+      const settings = await readSettings();
+      const daemon = await readDaemonState();
+      console.log(chalk.bold("\nAuthentication Status\n"));
+      console.log(chalk.gray(`Profile:  ${configuration.profile}`));
+      console.log(chalk.gray(`Server:   ${configuration.serverUrl}`));
+      console.log(chalk.gray(`Web app:  ${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();
@@ -8840,186 +10909,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 {
-      logger.debug("Stopping daemon for force auth...");
-      await stopDaemon();
-      if (!quiet) console.log(chalk.gray("\u2713 Stopped daemon"));
-    } catch (error) {
-      logger.debug("Daemon was not running or failed to stop:", error);
-    }
-    await clearCredentials();
-    if (!quiet) console.log(chalk.gray("\u2713 Cleared credentials"));
-    await clearMachineId();
-    if (!quiet) console.log(chalk.gray("\u2713 Cleared machine ID"));
-    if (!quiet) console.log("");
-  }
-  if (!forceAuth) {
-    const existingCreds = await readCredentials();
-    const settings = await 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: ${configuration.serverUrl}`));
-      console.log(chalk.gray(`  Web app: ${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 = configuration.flockbayHomeDir;
-  const credentials = await 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 = 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 (existsSync(dataDir)) {
-        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 = configuration.privateKeyFile;
-  if (!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(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 readCredentials();
-  const settings = await 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: ${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";
@@ -9645,6 +11542,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;
@@ -9667,10 +11573,112 @@ async function reauthForCurrentServerKeepingMachineId() {
   } catch {
   }
   await 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 = spawn("open", [u], { detached: true, stdio: "ignore" });
+      p2.unref();
+      return;
+    }
+    if (process.platform === "win32") {
+      const p2 = spawn("cmd", ["/c", "start", "", u], { detached: true, stdio: "ignore" });
+      p2.unref();
+      return;
+    }
+    const p = spawn("xdg-open", [u], { detached: true, stdio: "ignore" });
+    p.unref();
+  } catch {
+  }
+}
+async function fetchDaemonStatus() {
+  const state = await 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 readCredentials().catch(() => null);
+        const settings = await readSettings().catch(() => null);
+        const daemon = await readDaemonState().catch(() => null);
+        console.log(chalk.bold("\nFlockbay ready\n"));
+        console.log(chalk.gray(`Profile:  ${configuration.profile}`));
+        console.log(chalk.gray(`Server:   ${configuration.serverUrl}`));
+        console.log(chalk.gray(`Web app:  ${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(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", configuration.profile], {
     detached: true,
     stdio: "ignore",
     env: process.env
@@ -9685,7 +11693,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 readCredentials().catch(() => null);
+    const settings = await readSettings().catch(() => null);
+    const daemon = await readDaemonState().catch(() => null);
+    console.log(chalk.bold("\nFlockbay ready\n"));
+    console.log(chalk.gray(`Profile:  ${configuration.profile}`));
+    console.log(chalk.gray(`Server:   ${configuration.serverUrl}`));
+    console.log(chalk.gray(`Web app:  ${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(configuration.webappUrl);
     process.exit(0);
   } else {
     const latest = await getLatestDaemonLog();
@@ -9706,6 +11735,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: ${configuration.serverUrl}`));
+      if (unreachable.url) console.error(chalk.gray(`Failed request: ${unreachable.url}`));
+      if (/^https?:\/\/(127\.0\.0\.1|localhost)\b/i.test(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);
@@ -9716,10 +11758,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
 `);
@@ -9731,6 +11773,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()) {
@@ -9751,6 +11797,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") {
@@ -9774,6 +11823,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 readCredentials();
+    const settings = await readSettings();
+    const daemon = await readDaemonState();
+    console.log(chalk.bold("\nFlockbay Status\n"));
+    console.log(chalk.gray(`Profile: ${configuration.profile}`));
+    console.log(chalk.gray(`Server:   ${configuration.serverUrl}`));
+    console.log(chalk.gray(`Web app:  ${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 clearCredentials();
+    await clearMachineId();
+    console.log("Reset complete");
+    process.exit(0);
   } else if (subcommand === "connect") {
     try {
       await handleConnectCommand(args.slice(1));
@@ -9785,22 +11871,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;
@@ -9822,7 +11900,6 @@ ${engineRoot}`, {
           }
         }
       }
-      await handleAuthCommand(["login", "--force", "--quiet"]);
       await startDaemonDetachedOrExit();
     } catch (error) {
       console.error(chalk.red("Error:"), error instanceof Error ? error.message : "Unknown error");
@@ -9835,17 +11912,20 @@ ${engineRoot}`, {
   } else if (subcommand === "codex") {
     try {
       await chdirToNearestUprojectRootIfPresent();
-      const { runCodex } = await import('./runCodex-o6PCbHQ7.mjs');
+      const { runCodex } = await import('./runCodex-Di9eHddq.mjs');
       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) {
@@ -9927,11 +12007,14 @@ ${engineRoot}`, {
     }
     try {
       await chdirToNearestUprojectRootIfPresent();
-      const { runGemini } = await import('./runGemini-Bt0oEj_g.mjs');
+      const { runGemini } = await import('./runGemini-BS6sBU_V.mjs');
       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 {
@@ -9948,19 +12031,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) {
@@ -10089,6 +12160,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("=")) {
@@ -10265,4 +12338,4 @@ ${chalk.bold("Examples:")}
   }
 }
 
-export { ElicitationHub as E, MessageQueue2 as M, PLATFORM_SYSTEM_PROMPT as P, setLatestUserImages as a, MessageBuffer as b, consumeToolQuota as c, startFlockbayServer as d, detectUnrealProject as e, formatQuotaDeniedReason as f, buildProjectCapsule as g, hashObject as h, initialMachineMetadata as i, autoFinalizeCoordinationWorkItem as j, applyCoordinationSideEffectsFromMcpToolResult as k, stopCaffeinate as l, extractUserImagesMarker as m, notifyDaemonSessionStarted as n, getLatestUserImages as o, registerKillSessionHandler as r, shouldCountToolCall as s, trimIdent as t, withUserImagesMarker as w };
+export { ElicitationHub as E, MessageQueue2 as M, PLATFORM_SYSTEM_PROMPT as P, setLatestUserImages as a, MessageBuffer as b, consumeToolQuota as c, startFlockbayServer as d, detectUnrealProject as e, formatQuotaDeniedReason as f, buildProjectCapsule as g, hashObject as h, initialMachineMetadata as i, autoFinalizeCoordinationWorkItem as j, detectScreenshotsForGate as k, applyCoordinationSideEffectsFromMcpToolResult as l, stopCaffeinate as m, notifyDaemonSessionStarted as n, extractUserImagesMarker as o, getLatestUserImages as p, registerKillSessionHandler as r, shouldCountToolCall as s, trimIdent as t, withUserImagesMarker as w };