unity-open-mcp 0.9.0 → 1.1.0

package/dist/asmdef-discovery.d.ts

@@ -0,0 +1,35 @@
+export interface AsmdefCount {
+    /** Number of distinct compile assemblies in the project's own source. */
+    count: number;
+    /** A few sample asmdef paths (project-relative) for context/debugging. */
+    sample: string[];
+}
+/**
+ * Find the nearest `.asmdef` at or above `filePath`'s directory. Returns the
+ * asmdef's absolute path, or null when none is found before the filesystem
+ * root / hop limit. Maps any source file (absolute or relative) to its owning
+ * assembly so the caller can count how many distinct assemblies a set of errors
+ * spans.
+ *
+ * `projectRoot` anchors RELATIVE file paths (compiler errors carry project-
+ * relative paths like `Assets/Foo.cs`). Without it a relative path resolves
+ * against `process.cwd()`, which is rarely the Unity project and silently
+ * yields null for every file. Absolute paths ignore `projectRoot`.
+ */
+export declare function nearestAsmdef(filePath: string, projectRoot?: string | null): string | null;
+/**
+ * Count the project's own compile assemblies: `Assets/` + `Packages/` + any
+ * `file:`-referenced local packages from `Packages/manifest.json`. Registry
+ * packages (Library/PackageCache) are precompiled and excluded. Returns the
+ * distinct count and a small sample of project-relative paths. Memoized per
+ * project path.
+ */
+export declare function countProjectAsmdefs(projectPath: string | null | undefined): AsmdefCount;
+/**
+ * Distinct assemblies spanned by a set of compiler-error file paths. Returns
+ * the count of unique owning asmdefs (via {@link nearestAsmdef}); errors whose
+ * file does not map to an asmdef are dropped from the count. Pass the
+ * `projectRoot` so relative error-file paths (the usual `Assets/Foo.cs` form)
+ * resolve against the Unity project rather than `process.cwd()`.
+ */
+export declare function countAssembliesWithErrors(files: string[], projectRoot?: string | null): number;

package/dist/asmdef-discovery.js

@@ -0,0 +1,171 @@
+// Project assembly-definition discovery for read_compile_errors' partial-compile
+// signal (specs/feedback.md 2026-08-12). Unity compiles assemblies in dependency
+// order; when an early assembly fails the pipeline may not reach dependent ones,
+// so the CSxxxx errors in Editor.log can be a SUBSET of the true error set. This
+// module counts the project's own compile assemblies and maps an error's source
+// file to its owning assembly, so read_compile_errors can surface
+// `partialCompileLikely` + `assembliesWithErrors`/`asmdefCount` instead of letting
+// an agent treat `errorCount: N` as the complete picture.
+//
+// Scope: Assets/ + Packages/ + `file:`-referenced local packages from
+// manifest.json. Registry packages (Library/PackageCache) are precompiled and
+// excluded — they rarely carry compile errors and would inflate the count.
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join, dirname, resolve, relative, isAbsolute } from "node:path";
+const ASMDEF_RE = /\.asmdef$/i;
+// Directories never descended into when walking for asmdefs (build output,
+// caches, VCS, editor state).
+const SKIP_DIRS = new Set([
+    "Library",
+    "Temp",
+    "obj",
+    "node_modules",
+    ".git",
+    "Logs",
+    "UserSettings",
+    "Build",
+    "Builds",
+]);
+/** Maximum total asmdefs to collect (bounds the walk on huge projects). */
+const MAX_ASMDEFS = 500;
+/** Maximum parent-directory hops when locating an error file's owning asmdef. */
+const MAX_UP_WALK = 32;
+/**
+ * Find the nearest `.asmdef` at or above `filePath`'s directory. Returns the
+ * asmdef's absolute path, or null when none is found before the filesystem
+ * root / hop limit. Maps any source file (absolute or relative) to its owning
+ * assembly so the caller can count how many distinct assemblies a set of errors
+ * spans.
+ *
+ * `projectRoot` anchors RELATIVE file paths (compiler errors carry project-
+ * relative paths like `Assets/Foo.cs`). Without it a relative path resolves
+ * against `process.cwd()`, which is rarely the Unity project and silently
+ * yields null for every file. Absolute paths ignore `projectRoot`.
+ */
+export function nearestAsmdef(filePath, projectRoot) {
+    if (!filePath)
+        return null;
+    const anchored = projectRoot && !isAbsolute(filePath) ? resolve(projectRoot, filePath) : filePath;
+    let dir = dirname(resolve(anchored));
+    for (let guard = 0; guard < MAX_UP_WALK; guard++) {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return null; // unreadable dir — can't walk further reliably
+        }
+        const asmdef = entries.find((e) => ASMDEF_RE.test(e));
+        if (asmdef)
+            return join(dir, asmdef);
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return null;
+}
+/** Walk a directory tree collecting `.asmdef` paths, skipping build/cache dirs. */
+function walkAsmdefs(root, out) {
+    const stack = [root];
+    while (stack.length && out.size < MAX_ASMDEFS) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (out.size >= MAX_ASMDEFS)
+                break;
+            const full = join(dir, name);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (!SKIP_DIRS.has(name))
+                    stack.push(full);
+            }
+            else if (ASMDEF_RE.test(name)) {
+                out.add(full);
+            }
+        }
+    }
+}
+// Per-project memo. An asmdef layout changes rarely and the walk stats the
+// whole Assets/ tree synchronously, so cache the result for the session.
+const asmdefCountCache = new Map();
+/**
+ * Count the project's own compile assemblies: `Assets/` + `Packages/` + any
+ * `file:`-referenced local packages from `Packages/manifest.json`. Registry
+ * packages (Library/PackageCache) are precompiled and excluded. Returns the
+ * distinct count and a small sample of project-relative paths. Memoized per
+ * project path.
+ */
+export function countProjectAsmdefs(projectPath) {
+    if (!projectPath)
+        return { count: 0, sample: [] };
+    const cached = asmdefCountCache.get(projectPath);
+    if (cached)
+        return cached;
+    const found = new Set();
+    const assetsDir = join(projectPath, "Assets");
+    const packagesDir = join(projectPath, "Packages");
+    if (existsSync(assetsDir))
+        walkAsmdefs(assetsDir, found);
+    if (existsSync(packagesDir))
+        walkAsmdefs(packagesDir, found);
+    // file: packages referenced in manifest.json may live outside the project
+    // (e.g. "file:../../packages/bridge"). Unity resolves these relative to the
+    // Packages/ directory.
+    const manifestPath = join(packagesDir, "manifest.json");
+    if (existsSync(manifestPath)) {
+        try {
+            const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+            const deps = manifest.dependencies ?? {};
+            for (const v of Object.values(deps)) {
+                if (typeof v === "string" && v.startsWith("file:")) {
+                    const pkgPath = resolve(packagesDir, v.slice("file:".length));
+                    if (existsSync(pkgPath))
+                        walkAsmdefs(pkgPath, found);
+                }
+            }
+        }
+        catch {
+            // malformed/unreadable manifest — skip; Assets/ + Packages/ still counted.
+        }
+    }
+    const list = [...found];
+    const result = {
+        count: list.length,
+        sample: list.slice(0, 8).map((p) => {
+            const rel = relative(projectPath, p);
+            return rel || p;
+        }),
+    };
+    asmdefCountCache.set(projectPath, result);
+    return result;
+}
+/**
+ * Distinct assemblies spanned by a set of compiler-error file paths. Returns
+ * the count of unique owning asmdefs (via {@link nearestAsmdef}); errors whose
+ * file does not map to an asmdef are dropped from the count. Pass the
+ * `projectRoot` so relative error-file paths (the usual `Assets/Foo.cs` form)
+ * resolve against the Unity project rather than `process.cwd()`.
+ */
+export function countAssembliesWithErrors(files, projectRoot) {
+    const set = new Set();
+    for (const f of files) {
+        const a = nearestAsmdef(f, projectRoot);
+        if (a)
+            set.add(a);
+    }
+    return set.size;
+}
+//# sourceMappingURL=asmdef-discovery.js.map

package/dist/asmdef-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asmdef-discovery.js","sourceRoot":"","sources":["../src/asmdef-discovery.ts"],"names":[],"mappings":"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"}

package/dist/batch-spawn.d.ts

@@ -21,6 +21,33 @@ export declare function buildVerifyArgs(operation: string, args: Record<string,
 export declare function buildMetaArgs(operation: string, args: Record<string, unknown>): string[];
 export declare function encodeSpaces(value: string): string;
 export declare function classifyBatchFailure(combined: string): string | null;
+export interface EditorLockDiagnosis {
+    variant: "listener_up" | "listener_down" | "no_editor_found";
+    /** Short human-readable observation, e.g. "instance lock fresh (pid 123)". */
+    detail: string;
+}
+/**
+ * Observe the Editor state behind a project-lock conflict. Pure reads (lock
+ * file + PID liveness; process scan only when the lock is unusable) — never
+ * throws, never spawns Unity. `listener_up` vs `listener_down` distinguishes
+ * "the live bridge should answer" from "the Editor holds the lock but its
+ * listener is not up yet".
+ */
+export declare function diagnoseEditorLock(projectPath: string): EditorLockDiagnosis;
+/**
+ * Message for the `editor_instance_locked` error, naming the tool that was
+ * actually called (feedback 2026-08-17: the canned text said "the headless
+ * compile_check spawn" even for execute_menu).
+ */
+export declare function editorLockedMessage(toolName: string, diagnosis: EditorLockDiagnosis): string;
+/**
+ * Structured recovery hints for {@link editorLockedMessage}, one per variant.
+ * compile_check additionally keeps the read_compile_errors alternative (an
+ * open Editor makes a headless compile impossible, but the log is readable
+ * offline).
+ */
+export declare function editorLockedNextSteps(toolName: string, diagnosis: EditorLockDiagnosis): string[];
+export declare function extractOffendingPackages(combined: string): string[];
 export declare function buildUnityBatchArgs(operation: string, projectPath: string, executeMethod: string, toolArgs: string[]): string[];
 export declare class BatchClassificationError extends Error {
     readonly code: string;

package/dist/batch-spawn.js

@@ -1,8 +1,10 @@
 import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
 import { stat } from "node:fs/promises";
+import { trackBatchChild } from "./child-supervision.js";
 import { resolveUnityPath, scannedHubRoots } from "./unity-install-discovery.js";
-import { readInstanceLock, isPidAlive } from "./instance-discovery.js";
+import { readInstanceLock, isPidAlive, classifyInstance, } from "./instance-discovery.js";
+import { findUnityForProject } from "./running-unity.js";
 import { makeErrorResult } from "./results.js";
 import { VERIFY_JSON_BEGIN, VERIFY_JSON_END } from "./constants.js";
 const VERIFY_EXECUTE_METHOD = "UnityOpenMcpVerify.Batch.VerifyBatchEntry.Run";
@@ -254,16 +256,156 @@ export function encodeSpaces(value) {
 // situation apart from a genuine compile/spawn failure and act on it (close
 // the live Editor, or use live introspection instead of a headless spawn).
 //
+// Package-resolution failures get the same treatment: Unity bails at package
+// resolution BEFORE writing the VERIFY_JSON_BEGIN/END markers, so the generic
+// `batch_spawn_failed` / "did not contain JSON markers" error masks the real
+// root cause (an unresolvable Packages/manifest.json dependency). Surfacing
+// `project_load_failed` with the offending package stops an agent from
+// "fixing" a compile that never ran. See specs/feedback.md (compile_check
+// batch_spawn_failed).
+//
 // Returns the error code to emit, or null when the tail does not match a
 // known classification (caller falls back to batch_spawn_failed).
 const PROJECT_LOCK_PATTERN = /another unity instance|already open/i;
+// Unity prints these when the project fails to load at the package-resolution
+// stage — before the batch entry point ever runs, so no markers are emitted:
+//   - "Project has invalid dependencies" (Package Manager resolution failure)
+//   - "Package Manager Server process was shutdown" (backend process died)
+const PROJECT_LOAD_FAILED_PATTERN = /Project has invalid dependencies|Package Manager Server process was (?:shutdown|terminated)/i;
 export function classifyBatchFailure(combined) {
     if (typeof combined !== "string" || combined.length === 0)
         return null;
     if (PROJECT_LOCK_PATTERN.test(combined))
         return "editor_instance_locked";
+    if (PROJECT_LOAD_FAILED_PATTERN.test(combined))
+        return "project_load_failed";
     return null;
 }
+/**
+ * Observe the Editor state behind a project-lock conflict. Pure reads (lock
+ * file + PID liveness; process scan only when the lock is unusable) — never
+ * throws, never spawns Unity. `listener_up` vs `listener_down` distinguishes
+ * "the live bridge should answer" from "the Editor holds the lock but its
+ * listener is not up yet".
+ */
+export function diagnoseEditorLock(projectPath) {
+    const lock = projectPath
+        ? readInstanceLock(projectPath)
+        : null;
+    if (lock && isPidAlive(lock.pid)) {
+        const classification = classifyInstance(lock);
+        if (classification === "dead_bridge") {
+            return {
+                variant: "listener_down",
+                detail: `instance lock stale (pid ${lock.pid} alive, heartbeat not advancing — booting, Safe Mode, or failed bridge recompile)`,
+            };
+        }
+        return {
+            variant: "listener_up",
+            detail: `instance lock fresh (pid ${lock.pid}, state ${lock.state})`,
+        };
+    }
+    // No usable lock. A live Unity process for this project without a lock is
+    // the booting / Safe-Mode shape (the bridge writes its lock only after the
+    // listener binds — cold Safe Mode never writes one at all).
+    const process = findUnityForProject(projectPath);
+    if (process) {
+        return {
+            variant: "listener_down",
+            detail: `Unity process ${process.pid} matches the project but no live bridge lock exists (booting before the bridge starts, or Safe Mode)`,
+        };
+    }
+    return {
+        variant: "no_editor_found",
+        detail: "no live Unity process for this project found",
+    };
+}
+/**
+ * Message for the `editor_instance_locked` error, naming the tool that was
+ * actually called (feedback 2026-08-17: the canned text said "the headless
+ * compile_check spawn" even for execute_menu).
+ */
+export function editorLockedMessage(toolName, diagnosis) {
+    switch (diagnosis.variant) {
+        case "listener_up":
+            return (`A live Unity Editor holds the project lock, so the headless ${toolName} ` +
+                "spawn cannot open the project (Unity allows one Editor per project). " +
+                `(${diagnosis.detail}.) The Editor's bridge lock is fresh, so the live ` +
+                "bridge should be reachable — retry via the live route, or call " +
+                "unity_open_mcp_bridge_status to see why it is not answering.");
+        case "listener_down":
+            return (`A Unity Editor process holds the project lock but its bridge listener ` +
+                `is not up yet, so the headless ${toolName} spawn could not open the ` +
+                "project and the live route was unavailable too. " +
+                `(${diagnosis.detail}.) This is usually a booting Editor — wait for it ` +
+                "to finish starting, then retry; the call takes the live route once " +
+                "the listener is up.");
+        default:
+            return (`The headless ${toolName} spawn was refused with Unity's ` +
+                "one-Editor-per-project lock signature, but no live Unity process for " +
+                `this project was found (${diagnosis.detail}). The on-disk ` +
+                "Temp/UnityLockfile is likely stale from a crashed session.");
+    }
+}
+/**
+ * Structured recovery hints for {@link editorLockedMessage}, one per variant.
+ * compile_check additionally keeps the read_compile_errors alternative (an
+ * open Editor makes a headless compile impossible, but the log is readable
+ * offline).
+ */
+export function editorLockedNextSteps(toolName, diagnosis) {
+    switch (diagnosis.variant) {
+        case "listener_up":
+            return [
+                `A live Unity Editor holds the project lock, so the headless ${toolName} spawn cannot open the project (one Editor per project).`,
+                `The instance lock is fresh — the live bridge should be reachable. Call unity_open_mcp_ping or unity_open_mcp_bridge_status, then retry ${toolName} on the live route.`,
+                ...(toolName === "unity_open_mcp_compile_check"
+                    ? [
+                        "To verify compile state without closing the Editor, call unity_open_mcp_read_compile_errors (reads Editor.log offline; if its logSource is a prev_log_* value, the log was rotated — prefer the live bridge's compile signal).",
+                    ]
+                    : []),
+                `To run a true headless ${toolName}, close the live Editor first.`,
+            ];
+        case "listener_down":
+            return [
+                `A Unity Editor process holds the project but its bridge listener is not up yet (${diagnosis.detail}) — that is why the live route was unavailable and the headless ${toolName} spawn hit the project lock.`,
+                "Wait for the Editor to finish booting (typically well under a minute) and retry — the call takes the live route once the listener is up.",
+                "If it does not come up, call unity_open_mcp_bridge_status and unity_open_mcp_read_compile_errors: a failed bridge recompile shows there, and the remedy is to fix the C# errors, not to retry the spawn.",
+            ];
+        default:
+            return [
+                `The ${toolName} spawn was refused with Unity's project-lock signature, but no live Unity process for this project was found — Temp/UnityLockfile is likely stale from a crashed session.`,
+                "Verify no Unity instance holds the project (running processes), remove the stale <project>/Temp/UnityLockfile if none does, and retry.",
+            ];
+    }
+}
+// Capture the offending package id(s) from a Package Manager resolution
+// failure tail. Unity prints reverse-DNS package identifiers on lines like:
+//   [Package Manager] com.unity.modules.physicscore2d is not a valid package
+//   Missing or invalid dependencies: com.unity.modules.physicscore2d
+// We match com.*/org.* identifiers with at least three dot-separated labels
+// (so "com.unity" alone does not match), deduped and capped — best-effort,
+// since the exact phrasing varies across Unity versions. Returns the raw
+// matches in first-seen order.
+const PACKAGE_ID_PATTERN = /\b((?:com|org)\.[a-z0-9][a-z0-9_-]*(?:\.[a-z0-9][a-z0-9_-]*)+)\b/gi;
+export function extractOffendingPackages(combined) {
+    if (typeof combined !== "string" || combined.length === 0)
+        return [];
+    const seen = new Set();
+    const out = [];
+    PACKAGE_ID_PATTERN.lastIndex = 0;
+    let m;
+    while ((m = PACKAGE_ID_PATTERN.exec(combined)) !== null) {
+        const id = m[1];
+        if (!seen.has(id)) {
+            seen.add(id);
+            out.push(id);
+            if (out.length >= 8)
+                break; // cap; a wall of ids is not more useful
+        }
+    }
+    return out;
+}
 const UNITY_SPAWN_REFUSED_NEXT_STEPS = [
     "The Unity binary could not be executed (spawn refused or exit code 127). Do not retry compile_check blindly.",
     "Verify UNITY_PATH points to a valid Unity Editor executable, then call unity_open_mcp_read_compile_errors to check compile state without headless spawn.",
@@ -380,22 +522,28 @@ export class BatchSpawn {
             try {
                 const lock = readInstanceLock(this.projectPath);
                 if (lock && lock.pid && isPidAlive(lock.pid)) {
+                    // feedback 2026-08-17 — parameterize by the invoked tool and split
+                    // "live bridge should be up" from "Editor holds the lock but its
+                    // listener is not (booting / Safe Mode / failed recompile)". The old
+                    // canned text always described a compile_check spawn against a fully
+                    // live Editor, which misdirected agents calling any other tool.
+                    const diagnosis = diagnoseEditorLock(this.projectPath);
+                    const message = "A live Unity Editor holds the project lock, so the headless " +
+                        `spawn for '${toolName}' was not attempted (Unity allows one ` +
+                        "Editor per project, and the failed spawn would rotate Editor.log " +
+                        "and break read_compile_errors). " +
+                        editorLockedMessage(toolName, diagnosis);
                     return makeErrorResult({
                         code: "editor_instance_locked",
-                        message: "A live Unity Editor holds the project lock, so the headless " +
-                            "spawn was not attempted (Unity allows one Editor per project, " +
-                            "and the failed spawn would rotate Editor.log and break " +
-                            "read_compile_errors).",
+                        message,
                         detail: {
                             error: {
                                 code: "editor_instance_locked",
-                                message: "A live Unity Editor (pid " + lock.pid + ") holds the project lock.",
+                                message: "A live Unity Editor (pid " + lock.pid + ") holds the project lock. " +
+                                    diagnosis.detail,
+                                lockVariant: diagnosis.variant,
                             },
-                            agentNextSteps: [
-                                "A live Unity Editor holds the project lock, so the headless spawn cannot open the project (one Editor per project).",
-                                "To verify compile state without closing the Editor, call unity_open_mcp_read_compile_errors (reads Editor.log offline; if its logSource is a prev_log_* value, the log was rotated — prefer the live bridge's compile signal).",
-                                "Or close the live Editor and retry the batch spawn.",
-                            ],
+                            agentNextSteps: editorLockedNextSteps(toolName, diagnosis),
                         },
                     });
                 }
@@ -423,7 +571,7 @@ export class BatchSpawn {
         const argBuilder = verifyOperation ? buildVerifyArgs : buildMetaArgs;
         let parsed;
         try {
-            parsed = await this.spawnUnity(operation, args, executeMethod, argBuilder);
+            parsed = await this.spawnUnity(toolName, operation, args, executeMethod, argBuilder);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -520,7 +668,7 @@ export class BatchSpawn {
         }
         return null;
     }
-    spawnUnity(operation, args, executeMethod, argBuilder) {
+    spawnUnity(toolName, operation, args, executeMethod, argBuilder) {
         return new Promise((resolve, reject) => {
             const toolArgs = argBuilder(operation, args);
             const unityArgs = buildUnityBatchArgs(operation, this.projectPath, executeMethod, toolArgs);
@@ -532,6 +680,11 @@ export class BatchSpawn {
             const child = spawn(this.unityPath, unityArgs, {
                 stdio: ["ignore", "pipe", "pipe"],
             });
+            // Register with the process-wide supervision registry so the
+            // SIGINT/SIGTERM/exit handlers installed at the entry points tear this
+            // child down if the server dies mid-run (otherwise the headless Unity
+            // is orphaned holding the project lock until its own 10-min timeout).
+            trackBatchChild(child);
             // M13 — escalate SIGTERM → SIGKILL after a grace window so a wedged
             // Unity actually dies instead of lingering until the parent is killed.
             // The grace is short relative to the overall timeout but long enough for
@@ -603,19 +756,38 @@ export class BatchSpawn {
                     // recognizable signature when a live Editor already holds the
                     // project; emit editor_instance_locked so an agent can act (close
                     // the live Editor or use live introspection) instead of seeing an
-                    // opaque batch_spawn_failed.
+                    // opaque batch_spawn_failed. feedback 2026-08-17 — the message and
+                    // agentNextSteps name the invoked tool (not a canned compile_check)
+                    // and split "listener should be up" from "Editor booting / Safe
+                    // Mode / no Editor at all".
                     const classified = classifyBatchFailure(combined);
                     if (classified === "editor_instance_locked") {
-                        reject(new BatchClassificationError("editor_instance_locked", "A live Unity Editor holds the project lock, so the headless " +
-                            "compile_check spawn could not open the project. Unity allows " +
-                            "only one Editor per project. Either close the live Editor and " +
-                            "retry compile_check, or verify compile state via the live " +
-                            "bridge instead (execute_csharp + Library/ScriptAssemblies DLL " +
-                            "mtime check, or read_compile_errors).", [
-                            "A live Unity Editor holds the project lock, so the headless compile_check spawn cannot open the project (one Editor per project).",
-                            "To verify compile state without closing the Editor, call unity_open_mcp_read_compile_errors (reads Editor.log offline).",
-                            "To confirm a specific local package recompiled, call unity_open_mcp_reimport_package on the package and compare dllMtimeBefore/dllMtimeAfter.",
-                            "To run a true headless compile_check, close the live Editor first.",
+                        const diagnosis = this.projectPath
+                            ? diagnoseEditorLock(this.projectPath)
+                            : { variant: "no_editor_found", detail: "project path unknown" };
+                        reject(new BatchClassificationError("editor_instance_locked", editorLockedMessage(toolName, diagnosis), editorLockedNextSteps(toolName, diagnosis)));
+                        return;
+                    }
+                    if (classified === "project_load_failed") {
+                        // Unity bailed at package resolution BEFORE the batch entry point
+                        // ran, so no markers were emitted — the generic "did not contain
+                        // JSON markers" error would mask the real root cause (an
+                        // unresolvable Packages/manifest.json dependency). Name the
+                        // offending package(s) and point at read_compile_errors, which
+                        // surfaces the Package Manager notice without a headless spawn.
+                        const offending = extractOffendingPackages(combined);
+                        const pkgPart = offending.length > 0
+                            ? ` Offending package(s): ${offending.join(", ")}.`
+                            : "";
+                        reject(new BatchClassificationError("project_load_failed", `Batch Unity exited at package/project resolution (exit ${exitCode}) ` +
+                            `without running the batch entry point, so no compile took place. ` +
+                            `The project failed to load — this is NOT a C# compile error.${pkgPart} ` +
+                            `Check Packages/manifest.json for unresolvable dependencies and call ` +
+                            `unity_open_mcp_read_compile_errors to see the Package Manager notice.`, [
+                            `Batch Unity failed to load the project (exit ${exitCode}) before reaching the batch entry point — this is a package-resolution / project-load failure, not a compile failure.${pkgPart}`,
+                            "Call unity_open_mcp_read_compile_errors to read the Package Manager notice offline (no headless spawn).",
+                            "Inspect Packages/manifest.json and Packages/packages-lock.json for packages that cannot be resolved by the current Unity version.",
+                            "Do not retry compile_check blindly — the same project-load failure will recur until the manifest is fixed.",
                         ]));
                         return;
                     }
@@ -624,6 +796,28 @@ export class BatchSpawn {
                             `Path: '${this.unityPath}'.`, UNITY_SPAWN_REFUSED_NEXT_STEPS));
                         return;
                     }
+                    // Final generic fallback. Two cases reach here with no markers:
+                    //   - exit 0: Unity exited cleanly (likely a healthy compile) but
+                    //     emitted no markers — the async finalize path (BridgeBatchEntry
+                    //     → EditorApplication.update) did not fire. feedback 2026-08-15
+                    //     recurrence: this used to surface as the generic
+                    //     batch_spawn_failed code, so agents (and MCP hosts keying on
+                    //     isError) read a healthy compile as a spawn failure. It now
+                    //     carries the distinct `markers_missing` code with the
+                    //     confirm-via-read_compile_errors guidance.
+                    //   - non-zero: an unclassified spawn failure (stays
+                    //     batch_spawn_failed).
+                    if (exitCode === 0) {
+                        reject(new BatchClassificationError("markers_missing", `Batch output did not contain JSON markers. Exit code: 0.` +
+                            (tail ? ` Last output: ${tail}` : "") +
+                            ` Unity exited cleanly but emitted no markers after '${toolName}' ` +
+                            "(the async finalize path did not run) — the compile likely " +
+                            "succeeded. Call unity_open_mcp_read_compile_errors to confirm.", [
+                            `The ${toolName} batch Unity exited cleanly (exit 0) but emitted no JSON markers — the async finalize path did not run. This is usually a healthy compile with a missing report, not a spawn failure.`,
+                            "Call unity_open_mcp_read_compile_errors to confirm errorCount is 0 before treating the compile as passed.",
+                        ]));
+                        return;
+                    }
                     reject(new Error(`Batch output did not contain JSON markers. Exit code: ${exitCode}.` +
                         (tail ? ` Last output: ${tail}` : "")));
                     return;