unity-open-mcp 1.1.0 → 1.3.0

package/dist/project-path.js

@@ -0,0 +1,159 @@
+// Portable Unity project-path resolution.
+//
+// One resolver shared by the stdio server bootstrap (`index.ts`), the thin
+// CLI (`routers.ts` → `resolveEnv`), and the `setup` config writers. It turns
+// whatever the caller has — an env var, a `--project` flag, or nothing but the
+// spawn cwd — into ONE absolute Unity project root, so committed MCP client
+// config never has to carry a per-machine path.
+//
+// The module is deliberately light (only `node:fs` + `node:path`): `index.ts`
+// imports it statically on the pre-`getEnv()` path, which must not pull the
+// heavy ALL_TOOLS graph.
+import { existsSync, statSync } from "node:fs";
+import * as nodePath from "node:path";
+/** Directories that must exist directly under a Unity project root. */
+export const UNITY_ROOT_MARKERS = ["Assets", "Packages", "ProjectSettings"];
+export class ProjectPathError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ProjectPathError";
+    }
+}
+/**
+ * Resolve the Unity project root. First match wins:
+ *
+ *   1. `flagPath` (CLI `--project`) — an explicit argument beats ambient state.
+ *   2. `envPath` (`UNITY_PROJECT_PATH`) — keeps every existing client config
+ *      working, and wins over `--project-from-cwd` so a machine-local env
+ *      override can still redirect a committed config.
+ *   3. `projectFromCwd` (+ optional `unitySubpath`) — the portable path.
+ *   4. nothing → `ProjectPathError` with an actionable message.
+ *
+ * Relative `flagPath` / `envPath` values resolve against `cwd`, so
+ * `--project Client` works from a monorepo root. The result is always
+ * absolute: bridge port hashing and instance locks are keyed on it.
+ *
+ * Does NOT touch the filesystem — validation is `validateUnityProjectRoot`,
+ * which callers apply according to how strict they need to be.
+ */
+export function resolveProjectPath(options = {}) {
+    const p = options.pathApi ?? nodePath;
+    const cwd = options.cwd ?? process.cwd();
+    const flag = trimmed(options.flagPath);
+    if (flag)
+        return { absolute: absolutize(p, cwd, flag), source: "flag" };
+    const env = trimmed(options.envPath);
+    if (env)
+        return { absolute: absolutize(p, cwd, env), source: "env" };
+    if (options.projectFromCwd) {
+        const subpath = trimmed(options.unitySubpath);
+        if (subpath) {
+            if (p.isAbsolute(subpath)) {
+                throw new ProjectPathError("subpath_not_relative", `--unity-subpath must be relative to the workspace (received '${subpath}').`);
+            }
+            return {
+                absolute: absolutize(p, cwd, subpath),
+                source: "cwd+subpath",
+            };
+        }
+        return { absolute: absolutize(p, cwd, "."), source: "cwd" };
+    }
+    if (trimmed(options.unitySubpath)) {
+        throw new ProjectPathError("subpath_without_cwd", "--unity-subpath requires --project-from-cwd (or an explicit project path).");
+    }
+    throw new ProjectPathError("missing_project_path", missingProjectPathMessage());
+}
+/** Shared wording so the server, the CLI, and setup all suggest the same fix. */
+export function missingProjectPathMessage() {
+    return [
+        "No Unity project path. Use one of:",
+        "  --project-from-cwd                       run from the Unity project root",
+        "  --project-from-cwd --unity-subpath Client  monorepo: Unity project in a subfolder",
+        "  --project <path>                         explicit path (absolute or relative)",
+        "  UNITY_PROJECT_PATH=<path>                environment variable",
+    ].join("\n");
+}
+/**
+ * Check that `absolute` looks like a Unity project root (`Assets/`,
+ * `Packages/`, `ProjectSettings/`). Never throws — callers decide whether a
+ * miss is fatal.
+ */
+export function validateUnityProjectRoot(absolute) {
+    const missing = UNITY_ROOT_MARKERS.filter((marker) => {
+        const candidate = nodePath.join(absolute, marker);
+        try {
+            return !existsSync(candidate) || !statSync(candidate).isDirectory();
+        }
+        catch {
+            return true;
+        }
+    });
+    return { valid: missing.length === 0, missing };
+}
+/** One-line explanation of a failed {@link validateUnityProjectRoot}. */
+export function notUnityProjectMessage(resolved, validation) {
+    return (`${resolved.absolute} is not a Unity project root (from ${resolved.source}): ` +
+        `missing ${validation.missing.map((m) => `${m}/`).join(", ")}.`);
+}
+/**
+ * Pre-parse the portable project-path flags out of the stdio server's argv.
+ * Unknown tokens are ignored on purpose: MCP clients pass through arbitrary
+ * extra arguments, and the server has always tolerated them.
+ */
+export function parseServerFlags(argv) {
+    const flags = {
+        projectFromCwd: false,
+        unitySubpath: undefined,
+        error: undefined,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === "--project-from-cwd") {
+            flags.projectFromCwd = true;
+            continue;
+        }
+        if (tok === "--unity-subpath") {
+            const value = argv[i + 1];
+            if (!value || value.startsWith("-")) {
+                flags.error = "--unity-subpath requires a relative path (for example: Client).";
+                return flags;
+            }
+            flags.unitySubpath = value;
+            i++;
+            continue;
+        }
+        const inline = matchInline(tok, "--unity-subpath");
+        if (inline !== undefined) {
+            if (inline.length === 0) {
+                flags.error = "--unity-subpath requires a relative path (for example: Client).";
+                return flags;
+            }
+            flags.unitySubpath = inline;
+            continue;
+        }
+    }
+    return flags;
+}
+function matchInline(tok, flag) {
+    const prefix = `${flag}=`;
+    return tok.startsWith(prefix) ? tok.slice(prefix.length) : undefined;
+}
+function trimmed(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const t = value.trim();
+    return t.length > 0 ? t : undefined;
+}
+/**
+ * Resolve `input` against `cwd` and normalize. `p.resolve` already returns an
+ * absolute path and strips a trailing separator, which matters because the
+ * bridge port hash is taken over this exact string.
+ */
+function absolutize(p, cwd, input) {
+    return p.isAbsolute(input)
+        ? p.normalize(p.resolve(input))
+        : p.normalize(p.resolve(cwd, input));
+}
+//# sourceMappingURL=project-path.js.map

package/dist/project-path.js.map

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

package/dist/release-lookup.d.ts

@@ -0,0 +1,32 @@
+export declare const PACKAGE_NAME = "unity-open-mcp";
+export type ReleaseSource = "npm" | "github";
+export interface LatestVersion {
+    version: string;
+    source: ReleaseSource;
+    fallbackReason?: string;
+}
+export interface BridgeTagConfirmation {
+    confirmed: boolean;
+    error?: string;
+}
+/**
+ * Latest stable trio version: npm `latest` dist-tag first, GitHub `v*`
+ * releases as the fallback. Throws when neither source answers.
+ */
+export declare function resolveLatestVersion(fetchImpl: typeof globalThis.fetch): Promise<LatestVersion>;
+/**
+ * Whether the `bridge-v<version>` release tag exists on GitHub. Never throws:
+ * a failed lookup is reported as `confirmed: false` with the reason, because
+ * the caller's decision ("do not schedule a UPM re-pin to a tag we cannot
+ * prove exists") is the same either way.
+ */
+export declare function confirmBridgeReleaseTag(version: string, fetchImpl: typeof globalThis.fetch): Promise<BridgeTagConfirmation>;
+interface Semver {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease: string[];
+}
+export declare function parseSemver(value: string): Semver | null;
+export declare function compareSemver(a: string, b: string): number | null;
+export {};

package/dist/release-lookup.js

@@ -0,0 +1,147 @@
+// Published-release lookups shared by the `update` CLI command and the
+// `unity_open_mcp_upgrade` route.
+//
+// Both callers need the same two facts — "what is the latest trio version?"
+// and "does the bridge release tag for version X exist?" — and both must get
+// them WITHOUT going through the Unity Editor: the bridge's upgrade tool runs
+// on the Editor main thread, where a 10 s registry timeout would freeze the
+// Editor and the whole bridge request queue. The lookups therefore live here,
+// in the MCP server process, and the bridge only ever receives a resolved
+// `target_version`.
+//
+// Pure `fetch` + hand-rolled semver; no runtime dependencies.
+import { isRecord } from "./cli/json-guards.js";
+export const PACKAGE_NAME = "unity-open-mcp";
+const NPM_LATEST_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const GITHUB_RELEASES_URL = "https://api.github.com/repos/AlexeyPerov/Unity-Open-MCP/releases?per_page=30";
+// matching-refs is a PREFIX query: asking for bridge-v1.2.3 also lists
+// bridge-v1.2.30, so only the exact ref name proves the tag exists. Mirrors
+// LatestVersionCheck.ContainsExactBridgeTag on the bridge.
+const GITHUB_BRIDGE_TAG_URL = "https://api.github.com/repos/AlexeyPerov/Unity-Open-MCP/git/matching-refs/tags/bridge-v";
+const REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * Latest stable trio version: npm `latest` dist-tag first, GitHub `v*`
+ * releases as the fallback. Throws when neither source answers.
+ */
+export async function resolveLatestVersion(fetchImpl) {
+    let npmFailure = "npm registry lookup failed";
+    try {
+        const body = await fetchJson(fetchImpl, NPM_LATEST_URL);
+        const version = isRecord(body) ? body.version : undefined;
+        if (typeof version === "string" && parseSemver(version)) {
+            return { version, source: "npm" };
+        }
+        npmFailure = "npm registry returned no valid version";
+    }
+    catch (error) {
+        npmFailure = error instanceof Error ? error.message : String(error);
+    }
+    try {
+        const body = await fetchJson(fetchImpl, GITHUB_RELEASES_URL);
+        if (!Array.isArray(body))
+            throw new Error("GitHub returned an invalid release list");
+        const versions = body
+            .filter(isRecord)
+            .filter((release) => release.draft !== true && release.prerelease !== true)
+            .map((release) => release.tag_name)
+            .filter((tag) => typeof tag === "string" && /^v\d+\.\d+\.\d+$/.test(tag))
+            .map((tag) => tag.slice(1))
+            .filter((version) => parseSemver(version) !== null)
+            .sort((a, b) => compareSemver(b, a) ?? 0);
+        if (versions.length === 0)
+            throw new Error("GitHub has no stable trio release tag");
+        return { version: versions[0], source: "github", fallbackReason: npmFailure };
+    }
+    catch (error) {
+        const githubFailure = error instanceof Error ? error.message : String(error);
+        throw new Error(`npm: ${npmFailure}; GitHub: ${githubFailure}`);
+    }
+}
+/**
+ * Whether the `bridge-v<version>` release tag exists on GitHub. Never throws:
+ * a failed lookup is reported as `confirmed: false` with the reason, because
+ * the caller's decision ("do not schedule a UPM re-pin to a tag we cannot
+ * prove exists") is the same either way.
+ */
+export async function confirmBridgeReleaseTag(version, fetchImpl) {
+    if (!/^\d+\.\d+\.\d+$/.test(version)) {
+        return { confirmed: false, error: "Target version must be a plain X.Y.Z." };
+    }
+    try {
+        const body = await fetchJson(fetchImpl, `${GITHUB_BRIDGE_TAG_URL}${version}`);
+        if (!Array.isArray(body)) {
+            return { confirmed: false, error: "GitHub returned an invalid ref list." };
+        }
+        const exact = `refs/tags/bridge-v${version}`;
+        return body.some((ref) => isRecord(ref) && ref.ref === exact)
+            ? { confirmed: true }
+            : { confirmed: false, error: `Release tag bridge-v${version} was not found.` };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { confirmed: false, error: `Bridge tag check failed: ${message}` };
+    }
+}
+async function fetchJson(fetchImpl, url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(url, {
+            headers: { Accept: "application/json", "User-Agent": "unity-open-mcp-update" },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`${new URL(url).hostname} returned HTTP ${response.status}`);
+        }
+        return await response.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function parseSemver(value) {
+    const match = value.match(/^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+    if (!match)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4]?.split(".") ?? [],
+    };
+}
+export function compareSemver(a, b) {
+    const left = parseSemver(a);
+    const right = parseSemver(b);
+    if (!left || !right)
+        return null;
+    for (const key of ["major", "minor", "patch"]) {
+        if (left[key] !== right[key])
+            return left[key] > right[key] ? 1 : -1;
+    }
+    if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+        if (left.prerelease.length === right.prerelease.length)
+            return 0;
+        return left.prerelease.length === 0 ? 1 : -1;
+    }
+    const length = Math.max(left.prerelease.length, right.prerelease.length);
+    for (let index = 0; index < length; index++) {
+        const l = left.prerelease[index];
+        const r = right.prerelease[index];
+        if (l === undefined)
+            return -1;
+        if (r === undefined)
+            return 1;
+        if (l === r)
+            continue;
+        const lNumeric = /^\d+$/.test(l);
+        const rNumeric = /^\d+$/.test(r);
+        if (lNumeric && rNumeric)
+            return Number(l) > Number(r) ? 1 : -1;
+        if (lNumeric !== rNumeric)
+            return lNumeric ? -1 : 1;
+        return l > r ? 1 : -1;
+    }
+    return 0;
+}
+//# sourceMappingURL=release-lookup.js.map

package/dist/release-lookup.js.map

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

package/dist/routers.d.ts

@@ -5,8 +5,12 @@ import { PingCache } from "./ping-cache.js";
 import { ResourceRouter } from "./resource-router.js";
 import { BridgeEventStream } from "./event-stream.js";
 import { ToolSessionState } from "./tool-session-state.js";
+import { type ProjectPathSource } from "./project-path.js";
 export interface ResolvedEnv {
+    /** Normalized absolute Unity project root. */
     projectPath: string;
+    /** Which input produced {@link projectPath} (flag / env / cwd). */
+    projectPathSource: ProjectPathSource;
     port: number;
     authToken: string | undefined;
     /** Parsed UNITY_OPEN_MCP_BRIDGE_PORT (or CLI --port override), else undefined.
@@ -14,18 +18,28 @@ export interface ResolvedEnv {
      *  override precedence as construction (env override ⇒ no lock refresh). */
     envPort: number | undefined;
 }
+export interface ResolveEnvOptions {
+    /** `--project-from-cwd`: derive the Unity project root from the cwd. */
+    projectFromCwd?: boolean;
+    /** `--unity-subpath <rel>`: Unity project subfolder under the cwd. */
+    unitySubpath?: string;
+}
 /**
  * Resolve the project path / port / auth token from explicit overrides (CLI
  * flags) or the process env (MCP server). Throws when no project path is set —
  * callers print a friendly message and exit non-zero.
  *
- * Mirrors the precedence in index.ts#getEnv:
- *   projectPath: override > UNITY_PROJECT_PATH
+ * The project path goes through the shared `resolveProjectPath` resolver, so
+ * the CLI accepts exactly what the stdio server accepts: an absolute path, a
+ * path relative to the cwd (`--project Client` from a monorepo root), or no
+ * path at all with `--project-from-cwd [--unity-subpath Client]`.
+ *
+ *   projectPath: --project > UNITY_PROJECT_PATH > cwd (+ subpath)
  *   port:        override > UNITY_OPEN_MCP_BRIDGE_PORT > lock file > hash
  *   authToken:   discovered from the same lock as the port (no token with an
  *                explicit port override)
  */
-export declare function resolveEnv(projectPathOverride?: string, portOverride?: number): ResolvedEnv;
+export declare function resolveEnv(projectPathOverride?: string, portOverride?: number, options?: ResolveEnvOptions): ResolvedEnv;
 export declare class ResolveEnvError extends Error {
 }
 export interface RouterStack {

package/dist/routers.js

@@ -13,30 +13,50 @@ import { ResourceRouter } from "./resource-router.js";
 import { BridgeEventStream } from "./event-stream.js";
 import { resolvePort, resolveAuthToken } from "./instance-discovery.js";
 import { ToolSessionState } from "./tool-session-state.js";
+import { ProjectPathError, resolveProjectPath, } from "./project-path.js";
 import { PORT_ENV_VAR, PROJECT_PATH_ENV_VAR, bridgeBaseUrl, } from "./constants.js";
 /**
  * Resolve the project path / port / auth token from explicit overrides (CLI
  * flags) or the process env (MCP server). Throws when no project path is set —
  * callers print a friendly message and exit non-zero.
  *
- * Mirrors the precedence in index.ts#getEnv:
- *   projectPath: override > UNITY_PROJECT_PATH
+ * The project path goes through the shared `resolveProjectPath` resolver, so
+ * the CLI accepts exactly what the stdio server accepts: an absolute path, a
+ * path relative to the cwd (`--project Client` from a monorepo root), or no
+ * path at all with `--project-from-cwd [--unity-subpath Client]`.
+ *
+ *   projectPath: --project > UNITY_PROJECT_PATH > cwd (+ subpath)
  *   port:        override > UNITY_OPEN_MCP_BRIDGE_PORT > lock file > hash
  *   authToken:   discovered from the same lock as the port (no token with an
  *                explicit port override)
  */
-export function resolveEnv(projectPathOverride, portOverride) {
-    const projectPath = projectPathOverride ?? process.env[PROJECT_PATH_ENV_VAR];
-    if (!projectPath) {
-        throw new ResolveEnvError(`${PROJECT_PATH_ENV_VAR} environment variable is required ` +
-            "(or pass --project <path>).");
+export function resolveEnv(projectPathOverride, portOverride, options = {}) {
+    let resolvedProject;
+    try {
+        resolvedProject = resolveProjectPath({
+            flagPath: projectPathOverride,
+            envPath: process.env[PROJECT_PATH_ENV_VAR],
+            cwd: process.cwd(),
+            projectFromCwd: options.projectFromCwd,
+            unitySubpath: options.unitySubpath,
+        });
+    }
+    catch (err) {
+        throw new ResolveEnvError(err instanceof ProjectPathError ? err.message : String(err));
     }
+    const projectPath = resolvedProject.absolute;
     const rawEnvPort = process.env[PORT_ENV_VAR];
     const envPort = rawEnvPort ? parseInt(rawEnvPort, 10) : undefined;
     const effectiveEnvPort = rawEnvPort && Number.isInteger(envPort) ? envPort : undefined;
     const port = resolvePort(projectPath, portOverride ?? effectiveEnvPort);
     const authToken = resolveAuthToken(projectPath, portOverride ?? effectiveEnvPort);
-    return { projectPath, port, authToken, envPort: portOverride ?? effectiveEnvPort };
+    return {
+        projectPath,
+        projectPathSource: resolvedProject.source,
+        port,
+        authToken,
+        envPort: portOverride ?? effectiveEnvPort,
+    };
 }
 export class ResolveEnvError extends Error {
 }

package/dist/routers.js.map

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

package/dist/running-unity.d.ts

@@ -6,7 +6,14 @@ export interface RunningUnity {
     /** Normalized `-projectPath` argument, or null when it could not be parsed
      *  (Unity opened without `-projectPath`, e.g. via the Hub's "Open Editor"). */
     projectPath: string | null;
+    /** `true` when the command line carries `-batchmode`: a headless run (a
+     *  compile_check / verify spawn from this or another MCP server, a CI run),
+     *  never the interactive Editor a user owns. Optional so hand-built scanner
+     *  fixtures keep working. */
+    batchMode?: boolean;
 }
+/** `true` when the command line runs Unity headless (`-batchmode`, any case). */
+export declare function isBatchModeCommandLine(commandLine: string): boolean;
 /**
  * Pure `-projectPath` argument parser. Port of Hub
  * `running_unity.rs#parse_project_path_arg`. Accepts both the space-separated
@@ -106,6 +113,10 @@ export declare function setUnityProcessScannerForTest(fake: UnityProcessScanner
  * scan simply returns null and the caller falls back to its pre-feature
  * behavior. Documented in tests.
  *
+ * Skips headless batch children this server spawned and still supervises
+ * (see `child-supervision.ts`): they carry the same `-projectPath` but are
+ * tracked by the batch lease, not by Editor-ownership diagnostics.
+ *
  * Never throws: any scanner failure (ps missing, PowerShell slow, parse
  * error) returns null. A failed scan must not mask the underlying offline
  * state.
@@ -115,6 +126,16 @@ export declare function setUnityProcessScannerForTest(fake: UnityProcessScanner
 export declare function findUnityForProject(projectPath: string | null | undefined): {
     pid: number;
 } | null;
+/**
+ * A headless (`-batchmode`) Unity that ANOTHER process has open on
+ * `projectPath`: a compile_check / verify spawn from a second MCP server, or a
+ * CI run. This server's own supervised child is excluded (the batch lease
+ * accounts for it), and the interactive Editor is `findUnityForProject`'s
+ * business. Never throws; null when no such process is found.
+ */
+export declare function findHeadlessUnityForProject(projectPath: string | null | undefined): {
+    pid: number;
+} | null;
 /**
  * Read the full command line of a live process by PID. Cross-platform best
  * effort: macOS/Linux via `ps -p <pid> -o command=`, Windows via a PowerShell

package/dist/running-unity.js

@@ -29,6 +29,11 @@
 // two projects).
 import { execFileSync } from "node:child_process";
 import { normalizePath } from "./instance-discovery.js";
+import { isSupervisedBatchChildPid } from "./child-supervision.js";
+/** `true` when the command line runs Unity headless (`-batchmode`, any case). */
+export function isBatchModeCommandLine(commandLine) {
+    return /(^|\s)-batchmode(\s|$)/i.test(commandLine);
+}
 /**
  * Pure `-projectPath` argument parser. Port of Hub
  * `running_unity.rs#parse_project_path_arg`. Accepts both the space-separated
@@ -272,6 +277,7 @@ export function parsePsOutput(stdout) {
         out.push({
             pid,
             projectPath: projectPath !== null ? normalizePath(projectPath) : null,
+            batchMode: isBatchModeCommandLine(rest),
         });
     }
     return out;
@@ -305,6 +311,7 @@ export function parsePowerShellLines(stdout) {
         out.push({
             pid,
             projectPath: projectPath !== null ? normalizePath(projectPath) : null,
+            batchMode: rest.length > 0 && rest !== "null" && isBatchModeCommandLine(rest),
         });
     }
     return out;
@@ -385,6 +392,10 @@ export function setUnityProcessScannerForTest(fake) {
  * scan simply returns null and the caller falls back to its pre-feature
  * behavior. Documented in tests.
  *
+ * Skips headless batch children this server spawned and still supervises
+ * (see `child-supervision.ts`): they carry the same `-projectPath` but are
+ * tracked by the batch lease, not by Editor-ownership diagnostics.
+ *
  * Never throws: any scanner failure (ps missing, PowerShell slow, parse
  * error) returns null. A failed scan must not mask the underlying offline
  * state.
@@ -405,6 +416,45 @@ export function findUnityForProject(projectPath) {
         return null;
     }
     for (const proc of found) {
+        // Our own headless child is not an Editor the user owns; the batch lease
+        // accounts for it (and restart_editor must never pick it).
+        if (isSupervisedBatchChildPid(proc.pid))
+            continue;
+        // Neither is a -batchmode Unity another process started (a second MCP
+        // server's compile_check, a CI run): it is never in Safe Mode, must never
+        // be killed by restart_editor, and batch-spawn reports it separately
+        // (findHeadlessUnityForProject).
+        if (proc.batchMode)
+            continue;
+        if (proc.projectPath !== null && normalizePath(proc.projectPath) === target) {
+            return { pid: proc.pid };
+        }
+    }
+    return null;
+}
+/**
+ * A headless (`-batchmode`) Unity that ANOTHER process has open on
+ * `projectPath`: a compile_check / verify spawn from a second MCP server, or a
+ * CI run. This server's own supervised child is excluded (the batch lease
+ * accounts for it), and the interactive Editor is `findUnityForProject`'s
+ * business. Never throws; null when no such process is found.
+ */
+export function findHeadlessUnityForProject(projectPath) {
+    if (!projectPath)
+        return null;
+    const target = normalizePath(projectPath);
+    if (target.length === 0)
+        return null;
+    let found = [];
+    try {
+        found = getUnityProcessScanner().scan();
+    }
+    catch {
+        return null;
+    }
+    for (const proc of found) {
+        if (!proc.batchMode || isSupervisedBatchChildPid(proc.pid))
+            continue;
         if (proc.projectPath !== null && normalizePath(proc.projectPath) === target) {
             return { pid: proc.pid };
         }