flockbay 0.10.30 → 0.10.32

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

@@ -1,9 +1,11 @@
 import{createRequire as _pkgrollCR}from"node:module";const require=_pkgrollCR(import.meta.url);import chalk from 'chalk';
-import os, { homedir } from 'node:os';
+import * as os from 'node:os';
+import os__default, { homedir } from 'node:os';
 import { randomUUID, createCipheriv, randomBytes } from 'node:crypto';
-import { l as logger, p as projectPath, d as backoff, e as delay, R as RawJSONLinesSchema, c as configuration, f as readDaemonState, g as clearDaemonState, b as packageJson, r as readSettings, h as readCredentials, u as updateSettings, w as writeCredentials, i as unrealMcpPythonDir, j as acquireDaemonLock, k as writeDaemonState, m as ApiMachineClient, n as releaseDaemonLock, s as sendUnrealMcpTcpCommand, A as ApiClient, o as clearCredentials, q as clearMachineId, t as installUnrealMcpPluginToEngine, v as buildAndInstallUnrealMcpPlugin, x as getLatestDaemonLog, y as normalizeServerUrlForNode } from './types-DdJKBH6T.mjs';
+import { l as logger, p as projectPath, d as backoff, e as delay, R as RawJSONLinesSchema, c as configuration, f as readDaemonState, g as clearDaemonState, b as packageJson, r as readSettings, h as readCredentials, u as updateSettings, w as writeCredentials, i as unrealMcpPythonDir, j as acquireDaemonLock, k as writeDaemonState, m as ApiMachineClient, n as releaseDaemonLock, s as sendUnrealMcpTcpCommand, A as ApiClient, o as clearCredentials, q as clearMachineId, t as installUnrealMcpPluginToEngine, v as buildAndInstallUnrealMcpPlugin, x as getLatestDaemonLog, y as normalizeServerUrlForNode } from './types-6KOeU7L8.mjs';
 import { spawn, execFileSync, execSync } from 'node:child_process';
-import path, { resolve, join, dirname } from 'node:path';
+import * as path from 'node:path';
+import path__default, { resolve, join, dirname } from 'node:path';
 import { createInterface } from 'node:readline';
 import * as fs from 'node:fs';
 import fs__default, { existsSync, readFileSync, mkdirSync, readdirSync, accessSync, constants, statSync, createReadStream, writeFileSync, unlinkSync } from 'node:fs';
@@ -323,6 +325,10 @@ const PLATFORM_SYSTEM_PROMPT = trimIdent(`
   - 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.
+    - After launching Unreal Editor, do not \u201Crapid-retry\u201D reachability checks. Boot times vary by machine and project size.
+      - Prefer readiness checks (editor health / plugin reachable) spaced by increasing waits (bounded backoff).
+      - Default example ladder for editor boot: wait ~30s, then ~45s, then ~60s between checks (cap any single wait to 60s).
+      - Total cap: at most 240s of waiting for editor boot. If still not reachable, stop waiting and ask the user to tell you when the editor finishes booting (or to share what it shows on-screen).
 
     ## B) Screenshots (via UnrealMCP)
     Use UnrealMCP when the user asks for:
@@ -370,6 +376,24 @@ const PLATFORM_SYSTEM_PROMPT = trimIdent(`
   - Batch related questions into one call when possible.
   - If a user's request is too broad/unclear, ask him questions to clarify the scope and narrow down the work
 
+  # Timing / Waiting (realistic, increasing, bounded)
+
+  User machines vary widely (CPU, disk, GPU) and Unreal projects can be large. When you are waiting for something to become ready (editor boot, local server start, build finishing), you must use realistic waits.
+
+  - Prefer readiness checks over blind sleeps. Use sleeps only to space checks.
+  - Do not \u201Crapid-retry\u201D after starting heavyweight actions (editors, IDEs, emulators, big builds). Seconds-scale retry loops are a bad UX.
+  - Use bounded backoff:
+    - waits must increase between attempts (e.g. 10s \u2192 20s \u2192 40s \u2192 60s \u2026)
+    - cap any single wait to 60s
+    - cap total waiting to a reasonable maximum
+
+  Two tiers (keep it simple):
+  - Standard actions total cap: ~90s
+  - Heavyweight boots total cap: ~240s
+
+  If you expect something to take longer than the applicable total cap, do not pretend you can wait \u201Ca bit longer\u201D.
+  Stop waiting, explain what you\u2019re waiting for and what \u201Cready\u201D looks like, and ask the user to notify you when it completes.
+
   # Platform-provided context blocks
 
   The platform may prefix the user message with internal context blocks (machine/project hints, image markers, etc).
@@ -1987,9 +2011,9 @@ function resolveCandidatePath(candidate, cwd) {
   if (!raw) return raw;
   if (raw.startsWith("~/")) {
     const home = process.env.HOME || process.env.USERPROFILE || "";
-    if (home) return path.join(home, raw.slice(2));
+    if (home) return path__default.join(home, raw.slice(2));
   }
-  return path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+  return path__default.isAbsolute(raw) ? raw : path__default.resolve(cwd, raw);
 }
 function isImageBlock(block) {
   if (!block || typeof block !== "object") return false;
@@ -2025,7 +2049,7 @@ function extractScreenshotViewsFromText(text, cwd) {
     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\\")) {
+    if (!resolved.includes(`${path__default.sep}Saved${path__default.sep}Screenshots${path__default.sep}Flockbay${path__default.sep}`) && !resolved.includes("Saved/Screenshots/Flockbay/") && !resolved.includes("Saved\\Screenshots\\Flockbay\\")) {
       continue;
     }
     uniqPush(out, seen, resolved);
@@ -2035,7 +2059,7 @@ function extractScreenshotViewsFromText(text, cwd) {
     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 rel = path__default.join("Saved", "Screenshots", "Flockbay", filename);
       const resolved = resolveCandidatePath(rel, cwd);
       uniqPush(out, seen, resolved);
     }
@@ -2304,7 +2328,7 @@ async function claudeRemote(opts) {
         )) {
           didEmitAuthDiagnostic = true;
           const homeEnv = process.env.HOME ? String(process.env.HOME) : "";
-          const homedir = os.homedir();
+          const homedir = os__default.homedir();
           const forcedClaudePath = (process.env.FLOCKBAY_CLAUDE_PATH || process.env.FLOCKBAY_CLAUDE_CLI_PATH || "").trim();
           const pathHead = String(process.env.PATH || "").split(process.platform === "win32" ? ";" : ":").filter(Boolean).slice(0, 8).join(process.platform === "win32" ? ";" : ":");
           const diag = [
@@ -2319,7 +2343,7 @@ async function claudeRemote(opts) {
             "If you have multiple Claude installs, Flockbay remote prefers npm-global, then Homebrew, then native installer.",
             "You can force a specific install by setting `FLOCKBAY_CLAUDE_PATH` to the desired `cli.js` or binary path.",
             "",
-            `Diagnostics: user=${os.userInfo().username} platform=${process.platform} pid=${process.pid}`,
+            `Diagnostics: user=${os__default.userInfo().username} platform=${process.platform} pid=${process.pid}`,
             `Diagnostics: HOME(env)=${homeEnv || "(unset)"} os.homedir()=${homedir || "(unknown)"}`,
             `Diagnostics: FLOCKBAY_CLAUDE_PATH=${forcedClaudePath || "(unset)"}`,
             `Diagnostics: PATH(head)=${pathHead || "(unset)"}`,
@@ -2570,11 +2594,11 @@ class PermissionHandler {
     const raw = typeof filePath === "string" ? filePath.trim() : String(filePath ?? "").trim();
     if (!raw) return null;
     let candidate = raw.replace(/\\/g, "/");
-    if (path.isAbsolute(candidate)) {
+    if (path__default.isAbsolute(candidate)) {
       const base = String(this.session.path || "").trim();
       if (base) {
-        const rel = path.relative(base, candidate);
-        if (rel && !rel.startsWith("..") && !path.isAbsolute(rel)) {
+        const rel = path__default.relative(base, candidate);
+        if (rel && !rel.startsWith("..") && !path__default.isAbsolute(rel)) {
           candidate = rel.replace(/\\/g, "/");
         }
       }
@@ -3561,6 +3585,14 @@ function truncateCommitSubject(value, maxLen) {
   if (trimmed.length <= maxLen) return trimmed;
   return `${trimmed.slice(0, Math.max(0, maxLen - 1)).trimEnd()}\u2026`;
 }
+function normalizeFsPath(p) {
+  const resolved = path.resolve(String(p || ""));
+  const root = path.parse(resolved).root;
+  let normalized = resolved;
+  if (normalized !== root) normalized = normalized.replace(/[\\/]+$/, "");
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  return normalized;
+}
 async function runGit(args, cwd, timeoutMs) {
   const child = spawn("git", args, {
     cwd,
@@ -3605,11 +3637,11 @@ async function runGit(args, cwd, timeoutMs) {
   const exitCode = result.timedOut ? -1 : result.exitCode;
   return { ok: !result.timedOut && exitCode === 0, stdout: out, stderr: err, exitCode };
 }
-async function postJson(path, token, body) {
+async function postJson(path2, token, body) {
   const base = configuration.serverUrl.replace(/\/+$/, "");
   const timeoutMsRaw = String(process.env.FLOCKBAY_COORDINATION_HTTP_TIMEOUT_MS || "").trim();
   const timeoutMs = Number.isFinite(Number(timeoutMsRaw)) && Number(timeoutMsRaw) > 0 ? Number(timeoutMsRaw) : 7e3;
-  const url = `${base}${path}`;
+  const url = `${base}${path2}`;
   const res = await fetch(url, {
     method: "POST",
     headers: {
@@ -3639,6 +3671,26 @@ async function autoFinalizeCoordinationWorkItem(params) {
   if (!inRepo.ok || String(inRepo.stdout || "").trim().toLowerCase() !== "true") {
     return { ok: false, error: "not_a_git_repo" };
   }
+  const topLevel = await runGit(["rev-parse", "--show-toplevel"], cwd, 1e4);
+  if (!topLevel.ok) {
+    return { ok: false, error: topLevel.stderr || topLevel.stdout || "git_show_toplevel_failed" };
+  }
+  const repoRootRaw = String(topLevel.stdout || "").trim().split("\n")[0] || "";
+  const repoRoot = normalizeFsPath(repoRootRaw);
+  const homeDir = normalizeFsPath(os.homedir());
+  const fsRoot = normalizeFsPath(path.parse(repoRootRaw || repoRoot).root);
+  if (repoRoot && repoRoot === homeDir) {
+    return {
+      ok: false,
+      error: `unsafe_git_repo_root: repo root is your home directory (${repoRootRaw || repoRoot}). This usually means there's an accidental .git directory in your home folder. Fix by removing/renaming that .git and initializing git inside your project folder.`
+    };
+  }
+  if (repoRoot && repoRoot === fsRoot) {
+    return {
+      ok: false,
+      error: `unsafe_git_repo_root: repo root is the filesystem root (${repoRootRaw || repoRoot}). Auto-finalize refuses to run to avoid scanning massive folders.`
+    };
+  }
   const porcelain = await runGit(["status", "--porcelain=v1", "-z"], cwd, 2e4);
   if (!porcelain.ok) {
     return { ok: false, error: porcelain.stderr || porcelain.stdout || "git_status_failed" };
@@ -3700,6 +3752,28 @@ async function autoFinalizeCoordinationWorkItem(params) {
 
 async function claudeRemoteLauncher(session) {
   logger.debug("[claudeRemoteLauncher] Starting remote launcher");
+  const coordinationEnabled = Boolean(String(process.env.FLOCKBAY_COORDINATION_WORKSPACE_PROJECT_ID || "").trim() && String(process.env.FLOCKBAY_COORDINATION_WORK_ITEM_ID || "").trim());
+  let lastAutoFinalizeStatus = null;
+  const publishAutoFinalizeStatus = (next) => {
+    if (!coordinationEnabled) return false;
+    if (lastAutoFinalizeStatus && lastAutoFinalizeStatus.status === next.status && lastAutoFinalizeStatus.error === next.error) {
+      return false;
+    }
+    lastAutoFinalizeStatus = next;
+    try {
+      session.client.updateMetadata((metadata) => ({
+        ...metadata || {},
+        coordinationAutoFinalize: {
+          status: next.status,
+          error: next.error,
+          updatedAt: Date.now()
+        }
+      }));
+    } catch (e) {
+      logger.debug("[remote]: Failed to publish coordination auto-finalize status", e);
+    }
+    return true;
+  };
   const isLikelyAuthOrUsageError = (error) => {
     const message = error instanceof Error ? error.message : String(error);
     return /usage limit|quota|rate limit|resource exhausted|resource_exhausted|oauth token has expired|please run \/login|unauthenticated|unauthorized|forbidden|invalid (session )?token|needs authentication|setup-token|status 401|status 403|status 429|\b401\b|\b403\b|\b429\b/i.test(message);
@@ -3993,14 +4067,19 @@ async function claudeRemoteLauncher(session) {
                   summary: lastDeliveredMessage?.message ?? null
                 });
                 if (!finalizeRes.ok) {
-                  const msg = `Auto-finalize failed: ${finalizeRes.error}`;
-                  messageBuffer.addMessage(msg, "status");
-                  session.client.sendSessionEvent({ type: "message", message: msg });
+                  const err = String(finalizeRes.error || "").trim() || "auto_finalize_failed";
+                  if (publishAutoFinalizeStatus({ status: "error", error: err })) {
+                    messageBuffer.addMessage(`Auto-finalize failed: ${err}`, "status");
+                  }
+                } else {
+                  publishAutoFinalizeStatus({ status: "ok", error: null });
                 }
               } catch (err) {
-                const msg = `Auto-finalize failed: ${err instanceof Error ? err.message : String(err)}`;
-                messageBuffer.addMessage(msg, "status");
-                session.client.sendSessionEvent({ type: "message", message: msg });
+                const m = err instanceof Error ? err.message : String(err);
+                const errorMsg = String(m || "").trim() || "auto_finalize_failed";
+                if (publishAutoFinalizeStatus({ status: "error", error: errorMsg })) {
+                  messageBuffer.addMessage(`Auto-finalize failed: ${errorMsg}`, "status");
+                }
               }
             }
             if (!pending && session.queue.size() === 0) {
@@ -5126,7 +5205,7 @@ async function loginWithClerkAndPairMachine() {
   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(chalk.gray(`Machine: ${machineId} (${os__default.hostname()})`));
   console.log("");
   console.log("Open this link to sign in with Clerk and approve this machine:");
   console.log(approveUrl);
@@ -5222,8 +5301,8 @@ function startUnrealMcpServerForDaemon(options) {
     return { ok: false, errorMessage: `Missing Unreal MCP Python folder: ${pythonDir}` };
   }
   const flockbayHomeDir = options.flockbayHomeDir;
-  const runtimeDir = path.join(flockbayHomeDir, "unreal-mcp");
-  const logPath = path.join(runtimeDir, "unreal_mcp.log");
+  const runtimeDir = path__default.join(flockbayHomeDir, "unreal-mcp");
+  const logPath = path__default.join(runtimeDir, "unreal_mcp.log");
   try {
     fs__default.mkdirSync(runtimeDir, { recursive: true });
   } catch (err) {
@@ -5231,7 +5310,7 @@ function startUnrealMcpServerForDaemon(options) {
     return { ok: false, errorMessage: `Failed to create runtime folder: ${runtimeDir}
 Error: ${message}` };
   }
-  const uvProjectEnv = path.join(runtimeDir, "uv-venv");
+  const uvProjectEnv = path__default.join(runtimeDir, "uv-venv");
   const child = spawn("uv", ["run", "unreal_mcp_server.py"], {
     cwd: pythonDir,
     env: {
@@ -5492,9 +5571,9 @@ async function findNearestUprojectRoot(startDir) {
   if (current.toLowerCase().endsWith(".uproject")) {
     try {
       await fs$1.access(current);
-      return path.dirname(current);
+      return path__default.dirname(current);
     } catch {
-      current = path.dirname(current);
+      current = path__default.dirname(current);
     }
   }
   for (let i = 0; i < 25; i += 1) {
@@ -5503,7 +5582,7 @@ async function findNearestUprojectRoot(startDir) {
       if (entries.some((name) => name.toLowerCase().endsWith(".uproject"))) return current;
     } catch {
     }
-    const parent = path.dirname(current);
+    const parent = path__default.dirname(current);
     if (parent === current) break;
     current = parent;
   }
@@ -5514,7 +5593,7 @@ async function findFirstUprojectFile(projectRoot) {
     const entries = await fs$1.readdir(projectRoot);
     const uprojects = entries.filter((name) => name.toLowerCase().endsWith(".uproject")).sort();
     if (uprojects.length === 0) return null;
-    return path.join(projectRoot, uprojects[0]);
+    return path__default.join(projectRoot, uprojects[0]);
   } catch {
     return null;
   }
@@ -6567,9 +6646,9 @@ function targetPlatform() {
 }
 function buildScriptPath(engineRoot) {
   if (process.platform === "win32") {
-    return path.join(engineRoot, "Engine", "Build", "BatchFiles", "Build.bat");
+    return path__default.join(engineRoot, "Engine", "Build", "BatchFiles", "Build.bat");
   }
-  return path.join(engineRoot, "Engine", "Build", "BatchFiles", "Build.sh");
+  return path__default.join(engineRoot, "Engine", "Build", "BatchFiles", "Build.sh");
 }
 function parseBuildIssuesFromText(text, limit) {
   const issues = [];
@@ -6628,7 +6707,7 @@ async function buildUnrealProject(args) {
   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")) {
+  if (!uprojectPath || !path__default.isAbsolute(uprojectPath) || !uprojectPath.toLowerCase().endsWith(".uproject")) {
     return {
       ok: false,
       exitCode: null,
@@ -6665,12 +6744,12 @@ async function buildUnrealProject(args) {
       errorMessage: `Missing Unreal build script: ${script}`
     };
   }
-  const projectName = path.basename(uprojectPath).replace(/\.uproject$/i, "");
+  const projectName = path__default.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");
+  const logDir = args.logDir ?? path__default.join(path__default.dirname(uprojectPath), "Saved", "Logs", "Flockbay");
   fs__default.mkdirSync(logDir, { recursive: true });
-  const logPath = path.join(logDir, `flockbay_build_${Date.now()}.log`);
+  const logPath = path__default.join(logDir, `flockbay_build_${Date.now()}.log`);
   const buildArgs = [
     targetName,
     platform,
@@ -6758,9 +6837,9 @@ async function runUnrealSmokeTest(args) {
   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");
+  const screenshotDir = path__default.join(path__default.dirname(args.uprojectPath), "Saved", "Screenshots", "Flockbay");
   await mkdir(screenshotDir, { recursive: true });
-  const screenshotPath = path.join(screenshotDir, `Flockbay_smoke_test_${stampForFilename()}.png`);
+  const screenshotPath = path__default.join(screenshotDir, `Flockbay_smoke_test_${stampForFilename()}.png`);
   let started = false;
   let stopped = false;
   try {
@@ -7085,10 +7164,10 @@ async function readUprojectEngineAssociationOrNull(uprojectPath) {
 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(path__default.join(engineRoot, "Engine"))) return false;
+  const buildVersion = path__default.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") : "";
+  const editorCmd = process.platform === "darwin" ? path__default.join(engineRoot, "Engine", "Binaries", "Mac", "UnrealEditor-Cmd") : process.platform === "win32" ? path__default.join(engineRoot, "Engine", "Binaries", "Win64", "UnrealEditor-Cmd.exe") : process.platform === "linux" ? path__default.join(engineRoot, "Engine", "Binaries", "Linux", "UnrealEditor-Cmd") : "";
   if (editorCmd && existsSync(editorCmd)) return true;
   return false;
 }
@@ -7109,7 +7188,7 @@ function engineRootCandidatesForVersion(platform, version) {
   return [];
 }
 async function readEngineRootMajorMinorOrNull(engineRoot) {
-  const buildVersionPath = path.join(engineRoot, "Engine", "Build", "Build.version");
+  const buildVersionPath = path__default.join(engineRoot, "Engine", "Build", "Build.version");
   try {
     if (existsSync(buildVersionPath)) {
       const json = await readJsonFile(buildVersionPath);
@@ -7253,7 +7332,7 @@ async function uploadScreenshotViewsForSession(args) {
   const form = new FormData();
   for (const v of args.views) {
     const buf = await readFile(v.path);
-    const filename = path.basename(v.path);
+    const filename = path__default.basename(v.path);
     const contentType = (() => {
       const mime = detectImageMimeTypeFromBuffer$1(buf);
       if (mime) return mime;
@@ -7479,7 +7558,7 @@ async function startFlockbayServer(client, options) {
         let best = null;
         for (const name of entries) {
           if (!filter(name)) continue;
-          const full = path.join(dir, name);
+          const full = path__default.join(dir, name);
           let st;
           try {
             st = await stat(full);
@@ -7496,12 +7575,12 @@ async function startFlockbayServer(client, options) {
       }
     };
     const findLatestCrashDir = async (projectRoot) => {
-      const crashesDir = path.join(projectRoot, "Saved", "Crashes");
+      const crashesDir = path__default.join(projectRoot, "Saved", "Crashes");
       try {
         const entries = await readdir(crashesDir);
         let best = null;
         for (const name of entries) {
-          const full = path.join(crashesDir, name);
+          const full = path__default.join(crashesDir, name);
           let st;
           try {
             st = await stat(full);
@@ -7527,10 +7606,10 @@ async function startFlockbayServer(client, options) {
       }
     };
     const gatherCrashDiagnosticsBestEffort = async (uprojectPath) => {
-      const projectRoot = path.dirname(uprojectPath);
+      const projectRoot = path__default.dirname(uprojectPath);
       const summary = [];
       const detail = { uprojectPath, projectRoot };
-      const latestLog = await findLatestFile(path.join(projectRoot, "Saved", "Logs"), (n) => n.toLowerCase().endsWith(".log"));
+      const latestLog = await findLatestFile(path__default.join(projectRoot, "Saved", "Logs"), (n) => n.toLowerCase().endsWith(".log"));
       if (latestLog) {
         detail.projectLogPath = latestLog;
         const tail = await readFileTail(latestLog, 24e3);
@@ -7557,13 +7636,13 @@ async function startFlockbayServer(client, options) {
     const getUnrealEditorExe = (engineRoot) => {
       const root = engineRoot.trim().replace(/[\\/]+$/, "");
       if (process.platform === "darwin") {
-        return path.join(root, "Engine", "Binaries", "Mac", "UnrealEditor.app", "Contents", "MacOS", "UnrealEditor");
+        return path__default.join(root, "Engine", "Binaries", "Mac", "UnrealEditor.app", "Contents", "MacOS", "UnrealEditor");
       }
       if (process.platform === "win32") {
-        return path.join(root, "Engine", "Binaries", "Win64", "UnrealEditor.exe");
+        return path__default.join(root, "Engine", "Binaries", "Win64", "UnrealEditor.exe");
       }
       if (process.platform === "linux") {
-        return path.join(root, "Engine", "Binaries", "Linux", "UnrealEditor");
+        return path__default.join(root, "Engine", "Binaries", "Linux", "UnrealEditor");
       }
       return "";
     };
@@ -7732,12 +7811,46 @@ Next: fix the issue, then relaunch via unreal_editor_relaunch_last (or unreal_ed
       const exists = await runGit(["show-ref", "--verify", "--quiet", `refs/heads/${candidate}`], args.repoRoot, 1e4);
       if (exists.ok) return candidate;
     }
+    const hasCommit = await runGit(["rev-parse", "--verify", "HEAD"], args.repoRoot, 1e4);
+    if (!hasCommit.ok) {
+      throw new Error(
+        `Coordination requires an initial commit (no local branches exist yet).
+
+Fix:
+- Initialize: git init -b main
+- Add a minimal .gitignore
+- Commit: git add .gitignore && git commit -m "chore: init coordination"`
+      );
+    }
     const heads = await runGit(["for-each-ref", "--format=%(refname:short)", "refs/heads"], args.repoRoot, 1e4);
     const available = String(heads.stdout || "").split("\n").map((l) => l.trim()).filter(Boolean).slice(0, 20).join(", ");
     throw new Error(
       `Invalid base branch '${"main"}' (no local branch found). Create the branch locally (or rename your default branch). Available local branches: ${available || "(none)"}`
     );
   };
+  const publishCoordinationSetupStatus = (next) => {
+    try {
+      client?.updateMetadata?.((metadata) => ({
+        ...metadata || {},
+        coordinationAutoFinalize: {
+          status: next.status,
+          error: next.error,
+          updatedAt: Date.now()
+        }
+      }));
+    } catch (err) {
+      logger.debug("[flockbayMCP] Failed to publish coordination setup status:", err);
+    }
+  };
+  const classifyCoordinationGitError = (err) => {
+    const message = err instanceof Error ? err.message : String(err || "");
+    const detail = String(message || "").trim() || "coordination_git_error";
+    if (detail.startsWith("Not a git repo")) return { code: "not_a_git_repo", detail };
+    if (detail.startsWith("Coordination requires an initial commit")) return { code: "no_initial_commit", detail };
+    if (detail.startsWith("Invalid base branch")) return { code: "missing_base_branch", detail };
+    if (detail.includes("unsafe_git_repo_root")) return { code: "unsafe_git_repo_root", detail };
+    return { code: "coordination_git_error", detail };
+  };
   const preflightRefreshableFiles = async (args) => {
     const out = [];
     for (const filePath of args.files) {
@@ -7855,7 +7968,7 @@ ${String(st.stdout || "").trim()}`
   };
   const toolResultsArtifactsRoot = () => {
     const sessionDir = readSessionWorkingDirectory();
-    return path.join(sessionDir, ".flockbay", "artifacts", "tool-results");
+    return path__default.join(sessionDir, ".flockbay", "artifacts", "tool-results");
   };
   const safePathSegment = (raw) => String(raw || "").trim().replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+/, "").replace(/_+$/, "") || "unknown";
   const coerceTextBlocks = (content) => {
@@ -7871,9 +7984,9 @@ ${String(st.stdout || "").trim()}`
   };
   const writeToolResultArtifact = async (args) => {
     const root = toolResultsArtifactsRoot();
-    const toolDir = path.join(root, safePathSegment(args.toolName));
+    const toolDir = path__default.join(root, safePathSegment(args.toolName));
     await mkdir(toolDir, { recursive: true });
-    const filePath = path.join(toolDir, `${safePathSegment(args.toolResultId)}.json`);
+    const filePath = path__default.join(toolDir, `${safePathSegment(args.toolResultId)}.json`);
     const payload = {
       kind: "mcp_tool_result",
       toolName: args.toolName,
@@ -7894,7 +8007,9 @@ ${String(st.stdout || "").trim()}`
     const first = texts[0];
     if (first && !/^\s*[{[]/.test(first)) headLines.push(first);
     headLines.push(`Evidence: toolResultId=${args.artifact.id}`);
-    headLines.push(`Tip: use tool_result_query/tool_result_read for details (avoid re-reading full tool JSON unless necessary).`);
+    headLines.push(
+      `Tip: use tool_result_query (preferred) to fetch small slices; avoid cat/reading full .flockbay tool-result JSON unless necessary.`
+    );
     const modelContent = [{ type: "text", text: headLines.join("\n") }];
     if (args.passthroughContent && Array.isArray(args.fullResult?.content)) {
       for (const block of args.fullResult.content) {
@@ -7917,24 +8032,21 @@ ${String(st.stdout || "").trim()}`
   };
   const resolveToolResultArtifactPath = async (args) => {
     const root = toolResultsArtifactsRoot();
-    const resolvedRoot = path.resolve(root);
+    const resolvedRoot = path__default.resolve(root);
     const toolResultId = String(args.toolResultId || "").trim();
     if (!toolResultId) return { ok: false, error: "Missing toolResultId." };
-    const rawPath = String(args.artifactPath || "").trim();
     const toolName = String(args.toolName || "").trim();
     const safeId = safePathSegment(toolResultId);
     let filePath = "";
-    if (rawPath) {
-      filePath = rawPath;
-    } else if (toolName) {
-      filePath = path.join(root, safePathSegment(toolName), `${safeId}.json`);
+    if (toolName) {
+      filePath = path__default.join(root, safePathSegment(toolName), `${safeId}.json`);
     } else {
       if (!existsSync(root)) return { ok: false, error: `Tool results root not found: ${root}` };
       const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
       const matches = [];
       for (const entry of entries) {
         if (!entry.isDirectory()) continue;
-        const candidate = path.join(root, entry.name, `${safeId}.json`);
+        const candidate = path__default.join(root, entry.name, `${safeId}.json`);
         if (existsSync(candidate)) matches.push(candidate);
       }
       if (matches.length === 0) return { ok: false, error: `tool result not found: ${toolResultId}` };
@@ -7946,8 +8058,8 @@ ${String(st.stdout || "").trim()}`
       }
       filePath = matches[0];
     }
-    const resolvedFile = path.resolve(filePath);
-    if (!resolvedFile.startsWith(resolvedRoot + path.sep) && resolvedFile !== resolvedRoot) {
+    const resolvedFile = path__default.resolve(filePath);
+    if (!resolvedFile.startsWith(resolvedRoot + path__default.sep) && resolvedFile !== resolvedRoot) {
       return { ok: false, error: `Refusing to read outside tool-results root.` };
     }
     if (!existsSync(resolvedFile)) return { ok: false, error: `tool result artifact not found` };
@@ -8510,15 +8622,13 @@ ${String(st.stdout || "").trim()}`
       description: "Read a previously-stored MCP tool result artifact produced by Flockbay MCP (full tool input/output JSON). Use this when you explicitly need details beyond the default minimal tool observation.",
       inputSchema: {
         toolName: z.string().optional().describe("Tool name (folder under .flockbay/artifacts/tool-results)."),
-        toolResultId: z.string().describe("toolResultId from a prior tool observation."),
-        artifactPath: z.string().optional().describe("Optional absolute artifact path (advanced).")
+        toolResultId: z.string().describe("toolResultId from a prior tool observation.")
       }
     },
     async (args) => runWithMcpToolCard("tool_result_read", args, async () => {
       const toolName = typeof args?.toolName === "string" ? String(args.toolName).trim() : null;
       const toolResultId = typeof args?.toolResultId === "string" ? String(args.toolResultId).trim() : "";
-      const artifactPath = typeof args?.artifactPath === "string" ? String(args.artifactPath).trim() : null;
-      const resolved = await resolveToolResultArtifactPath({ toolName, toolResultId, artifactPath });
+      const resolved = await resolveToolResultArtifactPath({ toolName, toolResultId });
       if (!resolved.ok) return textToolResult(resolved.error, true);
       const raw = await readFile(resolved.path, "utf8");
       return {
@@ -8537,18 +8647,16 @@ ${String(st.stdout || "").trim()}`
       inputSchema: {
         toolName: z.string().optional().describe("Tool name (folder under .flockbay/artifacts/tool-results)."),
         toolResultId: z.string().describe("toolResultId from a prior tool observation."),
-        artifactPath: z.string().optional().describe("Optional absolute artifact path (advanced)."),
         paths: z.array(z.string()).min(1).describe('JSON pointer paths ("/output/result/location") or dot-paths ("output.result.location").')
       }
     },
     async (args) => runWithMcpToolCard("tool_result_query", args, async () => {
       const toolName = typeof args?.toolName === "string" ? String(args.toolName).trim() : null;
       const toolResultId = typeof args?.toolResultId === "string" ? String(args.toolResultId).trim() : "";
-      const artifactPath = typeof args?.artifactPath === "string" ? String(args.artifactPath).trim() : null;
       const paths = Array.isArray(args?.paths) ? args.paths.map((p) => String(p || "").trim()).filter(Boolean) : [];
       if (!toolResultId) return textToolResult("Missing toolResultId.", true);
       if (paths.length === 0) return textToolResult("Missing paths[] (provide one or more JSON paths).", true);
-      const resolved = await resolveToolResultArtifactPath({ toolName, toolResultId, artifactPath });
+      const resolved = await resolveToolResultArtifactPath({ toolName, toolResultId });
       if (!resolved.ok) return textToolResult(resolved.error, true);
       let json;
       try {
@@ -8633,8 +8741,29 @@ ${String(st.stdout || "").trim()}`
           return { content: [{ type: "text", text: "Missing files[]" }], isError: true };
         }
         const sessionCwd = readSessionWorkingDirectory();
-        const repoRoot = await resolveGitRepoRoot(sessionCwd);
-        const baseBranch = await resolveCoordinationBaseBranch({ projectId, repoRoot });
+        let repoRoot = "";
+        let baseBranch = "";
+        try {
+          repoRoot = await resolveGitRepoRoot(sessionCwd);
+          baseBranch = await resolveCoordinationBaseBranch({ projectId, repoRoot });
+          publishCoordinationSetupStatus({ status: "ok", error: null });
+        } catch (err) {
+          const classified = classifyCoordinationGitError(err);
+          publishCoordinationSetupStatus({ status: "error", error: classified.code });
+          return textToolResult(
+            JSON.stringify(
+              {
+                success: false,
+                error: classified.code,
+                detail: classified.detail,
+                hint: classified.code === "not_a_git_repo" ? "Initialize git in this project root (git init -b main) and add an initial commit, then retry." : classified.code === "no_initial_commit" ? "Create an initial commit so a base branch exists, then retry." : classified.code === "missing_base_branch" ? "Create/rename your base branch (main/master) locally, then retry." : "Fix the git repo and retry."
+              },
+              null,
+              2
+            ),
+            true
+          );
+        }
         const guard = client?.coordinationLeaseGuard;
         const needsRefresh = files.filter((f) => {
           try {
@@ -8868,8 +8997,28 @@ ${String(st.stdout || "").trim()}`
           return { content: [{ type: "text", text: "Missing files[]" }], isError: true };
         }
         const sessionCwd = readSessionWorkingDirectory();
-        const repoRoot = await resolveGitRepoRoot(sessionCwd);
-        const baseBranch = await resolveCoordinationBaseBranch({ projectId, repoRoot });
+        let repoRoot = "";
+        let baseBranch = "";
+        try {
+          repoRoot = await resolveGitRepoRoot(sessionCwd);
+          baseBranch = await resolveCoordinationBaseBranch({ projectId, repoRoot });
+          publishCoordinationSetupStatus({ status: "ok", error: null });
+        } catch (err) {
+          const classified = classifyCoordinationGitError(err);
+          publishCoordinationSetupStatus({ status: "error", error: classified.code });
+          return textToolResult(
+            JSON.stringify(
+              {
+                success: false,
+                error: classified.code,
+                detail: classified.detail
+              },
+              null,
+              2
+            ),
+            true
+          );
+        }
         const guard = client?.coordinationLeaseGuard;
         const needsRefresh = files.filter((f) => {
           try {
@@ -9015,10 +9164,10 @@ ${String(st.stdout || "").trim()}`
           if (!p) return p;
           if (p.startsWith("~/")) {
             const home = process.env.HOME || process.env.USERPROFILE || "";
-            if (home) return path.join(home, p.slice(2));
+            if (home) return path__default.join(home, p.slice(2));
           }
           const baseDir = readSessionWorkingDirectory();
-          return path.isAbsolute(p) ? p : path.resolve(baseDir, p);
+          return path__default.isAbsolute(p) ? p : path__default.resolve(baseDir, p);
         };
         const idsSeen = /* @__PURE__ */ new Set();
         const viewsLocal = [];
@@ -9031,7 +9180,7 @@ ${String(st.stdout || "").trim()}`
           if (!existsSync(abs)) {
             throw new Error(`Image not found: ${abs}`);
           }
-          const filename = path.basename(abs);
+          const filename = path__default.basename(abs);
           let id = deriveScreenshotViewIdFromFilename(filename);
           if (!id) id = filename.replace(/\.[^.]+$/, "");
           let unique = id;
@@ -9108,9 +9257,9 @@ ${String(st.stdout || "").trim()}`
     const limit = args.limit ?? 12;
     const includeBase64 = args.includeBase64 ?? false;
     const maxBytesPerImage = args.maxBytesPerImage ?? 25e5;
-    const outDir = path.join(path.dirname(uprojectPath), "Saved", "Screenshots", "Flockbay");
+    const outDir = path__default.join(path__default.dirname(uprojectPath), "Saved", "Screenshots", "Flockbay");
     try {
-      if (!uprojectPath || !uprojectPath.toLowerCase().endsWith(".uproject") || !path.isAbsolute(uprojectPath)) {
+      if (!uprojectPath || !uprojectPath.toLowerCase().endsWith(".uproject") || !path__default.isAbsolute(uprojectPath)) {
         return {
           content: [{ type: "text", text: `Invalid uprojectPath (must be an absolute path to *.uproject): ${String(uprojectPath)}` }],
           isError: true
@@ -9145,7 +9294,7 @@ ${String(st.stdout || "").trim()}`
       }
       const withTimes = await Promise.all(
         candidates.map(async (name) => {
-          const fullPath = path.join(outDir, name);
+          const fullPath = path__default.join(outDir, name);
           const st = await stat(fullPath);
           return { name, path: fullPath, mtimeMs: st.mtimeMs };
         })
@@ -9242,7 +9391,7 @@ ${String(st.stdout || "").trim()}`
     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)) {
+    if (!uprojectPath || !uprojectPath.toLowerCase().endsWith(".uproject") || !path__default.isAbsolute(uprojectPath)) {
       return {
         content: [{ type: "text", text: `Invalid uprojectPath (must be an absolute path to *.uproject): ${String(uprojectPath)}` }],
         isError: true
@@ -9330,7 +9479,7 @@ ${String(st.stdout || "").trim()}`
     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)) {
+    if (!uprojectPath || !uprojectPath.toLowerCase().endsWith(".uproject") || !path__default.isAbsolute(uprojectPath)) {
       return {
         content: [{ type: "text", text: `Invalid uprojectPath (must be an absolute path to *.uproject): ${String(uprojectPath)}` }],
         isError: true
@@ -10566,7 +10715,7 @@ ${String(st.stdout || "").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)) {
+    if (!uprojectPath || !uprojectPath.toLowerCase().endsWith(".uproject") || !path__default.isAbsolute(uprojectPath)) {
       return {
         content: [{ type: "text", text: `Invalid uprojectPath (must be an absolute path to *.uproject): ${String(uprojectPath)}` }],
         isError: true
@@ -10943,7 +11092,7 @@ async function buildProjectCapsule(opts) {
   if (!detection.projectRoot) return null;
   const projectRoot = detection.projectRoot;
   const uprojectFile = detection.uprojectFile;
-  const readmePath = path.join(projectRoot, ".flockbay", "README.md");
+  const readmePath = path__default.join(projectRoot, ".flockbay", "README.md");
   const readmeRaw = await readTextFileIfExists(readmePath);
   const maxReadmeChars = typeof opts.maxReadmeChars === "number" ? opts.maxReadmeChars : DEFAULT_MAX_README_CHARS;
   const readme = readmeRaw ? truncateWithNote(readmeRaw, maxReadmeChars) : null;
@@ -11005,14 +11154,14 @@ async function runClaude(credentials, options = {}) {
   let metadata = {
     path: workingDirectory,
     projectRootPath: coordinationProjectRootPath,
-    host: os.hostname(),
+    host: os__default.hostname(),
     version: packageJson.version,
-    os: os.platform(),
+    os: os__default.platform(),
     machineId,
     workspaceProjectId: coordinationWorkspaceProjectId,
     featureId: coordinationFeatureId,
     workItemId: coordinationWorkItemId,
-    homeDir: os.homedir(),
+    homeDir: os__default.homedir(),
     flockbayHomeDir: configuration.flockbayHomeDir,
     flockbayLibDir: projectPath(),
     flockbayToolsDir: resolve(projectPath(), "tools", "unpacked"),
@@ -11944,8 +12093,8 @@ ${authUrl}
 }
 
 async function syncCodexCliAuth(tokens) {
-  const authFilePath = path.join(os.homedir(), ".codex", "auth.json");
-  const authDir = path.dirname(authFilePath);
+  const authFilePath = path__default.join(os__default.homedir(), ".codex", "auth.json");
+  const authDir = path__default.dirname(authFilePath);
   let previousAccountId;
   let previousApiKey = null;
   try {
@@ -12127,10 +12276,10 @@ async function ensureDaemonRunning({ skipUnreal }) {
   throw new Error("daemon_start_timeout");
 }
 async function createSmokeWorkspaceDir(baseDir) {
-  const root = baseDir?.trim() ? path.resolve(baseDir) : path.join(os.tmpdir(), "flockbay-smoke", nowIsoCompact() + "_" + randomUUID().slice(0, 8));
+  const root = baseDir?.trim() ? path__default.resolve(baseDir) : path__default.join(os__default.tmpdir(), "flockbay-smoke", nowIsoCompact() + "_" + randomUUID().slice(0, 8));
   await fs$1.mkdir(root, { recursive: true });
   const secret = `SMOKE_SECRET_${randomUUID().slice(0, 8)}`;
-  await fs$1.writeFile(path.join(root, "smoke.txt"), `flockbay smoke test
+  await fs$1.writeFile(path__default.join(root, "smoke.txt"), `flockbay smoke test
 SMOKE_SECRET=${secret}
 `, "utf8");
   return { dir: root, secret };
@@ -12463,8 +12612,8 @@ async function handleSmokeTestCommand(args) {
   }
   const allOk = results.every((r) => r.ok);
   if (outPath) {
-    const abs = path.resolve(outPath);
-    await fs$1.mkdir(path.dirname(abs), { recursive: true });
+    const abs = path__default.resolve(outPath);
+    await fs$1.mkdir(path__default.dirname(abs), { recursive: true });
     await fs$1.writeFile(abs, JSON.stringify({ ok: allOk, results }, null, 2) + "\n", "utf8");
     console.log(chalk.gray(`Wrote: ${abs}`));
   }
@@ -12518,7 +12667,7 @@ async function waitForUnreal(options) {
   };
 }
 function resolveUnrealEditorExe(engineRoot) {
-  const exe = process.platform === "win32" ? path.join(engineRoot, "Engine", "Binaries", "Win64", "UnrealEditor.exe") : path.join(engineRoot, "Engine", "Binaries", process.platform === "darwin" ? "Mac" : "Linux", "UnrealEditor");
+  const exe = process.platform === "win32" ? path__default.join(engineRoot, "Engine", "Binaries", "Win64", "UnrealEditor.exe") : path__default.join(engineRoot, "Engine", "Binaries", process.platform === "darwin" ? "Mac" : "Linux", "UnrealEditor");
   return exe;
 }
 async function runRuntimeSmoke(options) {
@@ -12595,10 +12744,10 @@ Expected FriendlyName="Flockbay MCP" CreatedBy="Respaced Inc."`
     await sendUnrealMcpTcpCommand({ type: "play_in_editor_windowed", host: options.host, port: options.port, timeoutMs: Math.max(options.timeoutMs, 2e4) });
     await new Promise((r) => setTimeout(r, 1e3));
     await sendUnrealMcpTcpCommand({ type: "stop_play_in_editor", host: options.host, port: options.port, timeoutMs: Math.max(options.timeoutMs, 2e4) });
-    const projectDir = path.dirname(options.projectPath);
-    const shotsDir = path.join(projectDir, "Saved", "Screenshots", "Flockbay");
+    const projectDir = path__default.dirname(options.projectPath);
+    const shotsDir = path__default.join(projectDir, "Saved", "Screenshots", "Flockbay");
     ensureDir(shotsDir);
-    const shotPath = path.join(shotsDir, `smoke_${Date.now()}.png`);
+    const shotPath = path__default.join(shotsDir, `smoke_${Date.now()}.png`);
     await sendUnrealMcpTcpCommand({
       type: "take_screenshot",
       params: { filepath: shotPath },
@@ -13248,7 +13397,7 @@ ${engineRoot}`, {
   } else if (subcommand === "codex") {
     try {
       await chdirToNearestUprojectRootIfPresent();
-      const { runCodex } = await import('./runCodex-B0JRo8YP.mjs');
+      const { runCodex } = await import('./runCodex-F93OWlPh.mjs');
       let startedBy = void 0;
       let sessionId = void 0;
       for (let i = 1; i < args.length; i++) {
@@ -13350,7 +13499,7 @@ ${engineRoot}`, {
     }
     try {
       await chdirToNearestUprojectRootIfPresent();
-      const { runGemini } = await import('./runGemini-DO9xzjyY.mjs');
+      const { runGemini } = await import('./runGemini-Cvo7a4eh.mjs');
       let startedBy = void 0;
       let sessionId = void 0;
       for (let i = 1; i < args.length; i++) {