@npgamedev/godot-mcp-server 0.0.1 → 1.0.0

package/dist/registration/toolRegistry.js

@@ -0,0 +1,211 @@
+import { isReadOnly, isExcludedByReadOnly } from "../security/profiles.js";
+import { setToolRef } from "./toolRefs.js";
+import { isVersionCompatible } from "../shared/version.js";
+import { checkPathGuard } from "../security/pathGuard.js";
+import { toolError } from "../shared/errorContract.js";
+import { isRawJsonSchema, jsonSchemaToZodShape, addStringCoercion } from "../shared/schemaCoercion.js";
+import { callAndWrap, injectSuccessHint } from "./toolDispatch.js";
+/** Global hook pipeline — set once at startup via setGlobalHookPipeline. */
+let globalHookPipeline = undefined;
+/**
+ * Set the global hook pipeline. Called once at server startup.
+ * @internal
+ */
+export function setGlobalHookPipeline(pipeline) {
+    globalHookPipeline = pipeline;
+}
+/** Version gate map — populated by registerToolWrapped callers. */
+const versionMap = new Map();
+/**
+ * Plain-language, inclusive, range-aware support clause for a version-gated
+ * tool's bounds. Used ONLY in the UNSUPPORTED error hint (the runtime version
+ * gate below) — never in a success/regular hint, tool-def successHint, or
+ * schema description. The gate guarantees at least one bound is set, so the
+ * final return covers the max-only case. The "–" between bounds is an en-dash
+ * (U+2013).
+ * @internal
+ */
+export function versionSupportText(min, max) {
+    if (min && max)
+        return `Supported on Godot ${min}–${max} (inclusive).`;
+    if (min)
+        return `Requires Godot ${min} or newer.`;
+    return `Supported up to Godot ${max} (inclusive).`;
+}
+/**
+ * Path-guard map (built-in tools only) — name → declared PathGuards. Consulted
+ * in the dispatch choke point (wrappedHandler) to syntactically pre-filter
+ * path params before the bridge round-trip. Extension tools register without
+ * pathParams, so they never have an entry here (toolkit enforces their guards).
+ */
+const pathParamMap = new Map();
+/**
+ * Suppress per-tool sendToolListChanged() notifications during a batch
+ * operation, then emit a single notification at the end. Use this when
+ * registering multiple tools in a tight loop.
+ */
+export function batchToolRegistration(server, fn) {
+    const orig = server.sendToolListChanged.bind(server);
+    server.sendToolListChanged = () => { };
+    try {
+        fn();
+    }
+    finally {
+        server.sendToolListChanged = orig;
+        server.sendToolListChanged();
+    }
+}
+/**
+ * Register one tool through the wrapped, pre-flighted path — the **only**
+ * sanctioned way to install a tool. Wraps the SDK handler with a runtime version
+ * gate, a syntactic path pre-filter, and the hook pipeline, then records the tool
+ * ref for later lookup and in-place description refresh.
+ *
+ * @param name - the tool's MCP wire name (what the client calls)
+ * @param config - the SDK tool config (description, `inputSchema`, annotations);
+ *   raw JSON-Schema from extensions is converted to Zod, and string coercion is
+ *   added so agents may pass JSON-encoded scalars for array/object/number params
+ * @param handler - the dispatch function invoked on a call, after every pre-flight check passes
+ * @param opts - version bounds, an explicit hook pipeline (falls back to the
+ *   global one), and path-guard declarations to pre-filter before the bridge round-trip
+ *
+ * @remarks
+ * Version-gated tools are filtered out at registration when the connected Godot
+ * version is known and incompatible, and **skipped** when the version is not yet
+ * known — the startup reconcile re-runs registration once it resolves. A second,
+ * defence-in-depth version check runs per call to catch a reconnect to a different
+ * Godot version.
+ *
+ * @example
+ * ```ts
+ * registerToolWrapped(
+ *   server,
+ *   bridge,
+ *   "my_tool",
+ *   { description: "…", inputSchema: { path: z.string() } },
+ *   (input) => handleMyTool(bridge, input),
+ *   { godotMinVersion: "4.5", pathParams: [{ param: "path", guard: "project" }] },
+ * );
+ * ```
+ */
+export function registerToolWrapped(server, bridge, name, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- McpServer.registerTool has complex overloaded types
+config, handler, opts = {}) {
+    // Convert raw JSON Schema (from extensions) to Zod shape for SDK compat.
+    if (config.inputSchema && isRawJsonSchema(config.inputSchema)) {
+        config = { ...config, inputSchema: jsonSchemaToZodShape(config.inputSchema) };
+    }
+    // Add LLM string coercion to all Zod shapes — agents sometimes send
+    // JSON-encoded strings for array/object/number params.
+    if (config.inputSchema && !isRawJsonSchema(config.inputSchema)) {
+        config = { ...config, inputSchema: addStringCoercion(config.inputSchema) };
+    }
+    if (opts.godotMinVersion != null || opts.godotMaxVersion != null) {
+        versionMap.set(name, { min: opts.godotMinVersion, max: opts.godotMaxVersion });
+    }
+    if (opts.pathParams != null && opts.pathParams.length > 0) {
+        pathParamMap.set(name, opts.pathParams);
+    }
+    // Registration-time version filter: skip version-gated tools when the
+    // connected Godot version is known and incompatible.
+    if (opts.godotMinVersion != null || opts.godotMaxVersion != null) {
+        const connected = bridge.getGodotVersion();
+        if (connected == null) {
+            // Version unknown — skip the tool (don't register something we can't
+            // verify). It is registered once the version resolves: the version-
+            // resolved startup reconcile re-runs registration when the editor first
+            // reports its version (startup/reconcile.ts maybeStartupReconcile →
+            // handleConfigReload — the server-before-editor cold start), and any
+            // later reconnect re-runs it through handleConfigReload as well.
+            return;
+        }
+        if (!isVersionCompatible(connected, opts.godotMinVersion, opts.godotMaxVersion)) {
+            return;
+        }
+    }
+    // The SDK passes (args, extra) to tool handlers; extra.signal is an
+    // AbortSignal that fires when the MCP client sends notifications/cancelled.
+    // Defensive: extra may be undefined if the SDK omits it (observed with
+    // some client versions) — use optional chaining.
+    const wrappedHandler = async (input, extra) => {
+        const signal = extra?.signal;
+        // Defence-in-depth: runtime version check for version-gated tools
+        // (catches reconnect to a different Godot version).
+        const verBounds = versionMap.get(name);
+        if (verBounds != null) {
+            const connected = bridge.getGodotVersion();
+            if (connected != null && !isVersionCompatible(connected, verBounds.min, verBounds.max)) {
+                const supported = versionSupportText(verBounds.min, verBounds.max);
+                return toolError("UNSUPPORTED", `${name} is not supported on this Godot version (connected: ${connected[0]}.${connected[1]})`, `${supported} Use classdb.get_info for alternatives.`);
+            }
+        }
+        // Syntactic path pre-filter (built-in tools only) — fast-fail an
+        // out-of-bounds path before the WS round-trip. Strict subset of the
+        // toolkit's FileGuard (the authoritative boundary); the invariant lives
+        // in src/security/pathGuard.ts.
+        const guards = pathParamMap.get(name);
+        if (guards) {
+            for (const g of guards) {
+                const verdict = checkPathGuard(g, input?.[g.param]);
+                if (!verdict.ok) {
+                    return toolError("PATH_DENIED", `path rejected (${g.param}): ${verdict.reason}`, "Use a project-relative res:// path (user:// for save_* tools). The toolkit is the authoritative guard.");
+                }
+            }
+        }
+        // Hook pipeline (explicit or global)
+        const pipeline = opts.hookPipeline ?? globalHookPipeline;
+        if (pipeline) {
+            return pipeline.execute({ name, input: (input ?? {}) }, () => handler(input, signal));
+        }
+        return handler(input, signal);
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- handler 2-arg shape doesn't match SDK overloads
+    const ref = server.registerTool(name, config, wrappedHandler);
+    setToolRef(name, ref);
+}
+/**
+ * Bulk-register an array of {@link ToolDef}s, each through
+ * {@link registerToolWrapped}. The default handler calls the bridge and
+ * JSON-stringifies the result — the path most built-in tool modules follow.
+ *
+ * @param tools - the tool definitions to register (catalogue order preserved)
+ * @param allowedTools - when set, an allowlist: a tool absent from the set is
+ *   skipped (the per-module surface filter); omit to register every tool
+ * @param opts - `handlers` supplies per-tool overrides for modules with custom
+ *   response shaping (screenshots, summary-first) — these still get `successHint`
+ *   injection; `hookPipeline` overrides the global pipeline
+ *
+ * @remarks
+ * In read-only mode, tools excluded by their annotations are skipped here — the
+ * same gate the live SDK surface enforces.
+ */
+export function registerTools(server, bridge, tools, allowedTools, opts = {}) {
+    const readOnly = isReadOnly();
+    for (const tool of tools) {
+        if (allowedTools && !allowedTools.has(tool.name))
+            continue;
+        if (isExcludedByReadOnly(readOnly, tool.annotations))
+            continue;
+        const description = tool.description;
+        const customHandler = opts.handlers?.get(tool.name);
+        let handler = (customHandler ??
+            ((input, signal) => callAndWrap(bridge, tool.method, input, { signal, successHint: tool.successHint })));
+        // Custom handlers bypass callAndWrap, so inject successHint via wrapper.
+        if (customHandler && tool.successHint) {
+            const baseHandler = handler;
+            const hintText = tool.successHint;
+            handler = (async (input, signal) => {
+                const result = await baseHandler(input, signal);
+                if (!result.isError)
+                    injectSuccessHint(result, hintText);
+                return result;
+            });
+        }
+        registerToolWrapped(server, bridge, tool.name, { description, inputSchema: tool.inputSchema, annotations: tool.annotations }, handler, {
+            godotMinVersion: tool.godotMinVersion,
+            godotMaxVersion: tool.godotMaxVersion,
+            hookPipeline: opts.hookPipeline,
+            pathParams: tool.pathParams,
+        });
+    }
+}

package/dist/registry.js

@@ -0,0 +1,291 @@
+/**
+ * System-wide project registry reader.
+ *
+ * Mirrors the GDScript `registry_client.gd` — same file, same schema, same path
+ * normalisation. The plugin writes; this module reads. Resolves a project's
+ * editor / runtime / LSP endpoints by absolute path, and optionally watches the
+ * registry file so runtime-port changes push to the bridge without per-RPC I/O.
+ *
+ * Reading includes deciding whether an entry's owner is still there: the plugin
+ * has no reliable liveness signal of its own and prunes nothing, so entries
+ * accumulate. That check is delegated to `registryLiveness` — still a read, kept
+ * out of here so the socket mechanics don't blur the schema reader.
+ *
+ * @module
+ */
+import { readFileSync, watch, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { isPidAlive, wsPortNotRefused } from "./registryLiveness.js";
+// -- Path helpers ------------------------------------------------------------
+/** Canonical path form: forward slashes, no trailing slash, lowercase on Windows. */
+export function normalizePath(p) {
+    let n = p.replace(/\\/g, "/").replace(/\/+$/, "");
+    // Windows and macOS default filesystems are case-insensitive; lowercase
+    // avoids mismatches between Godot's globalize_path and Node.js
+    // process.cwd() which may differ in casing.
+    if (process.platform === "win32" || process.platform === "darwin")
+        n = n.toLowerCase();
+    return n;
+}
+/** OS-specific registry file path — must match registry_client.gd. */
+export function registryPath() {
+    switch (process.platform) {
+        case "win32":
+            return join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "godot-mcp-toolkit", "projects.json");
+        case "darwin":
+            return join(homedir(), "Library", "Application Support", "godot-mcp-toolkit", "projects.json");
+        default:
+            return join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "godot-mcp-toolkit", "projects.json");
+    }
+}
+// -- Registry I/O ------------------------------------------------------------
+function readRegistry() {
+    // Single parse attempt — no retry, no busy-wait. The toolkit writes the
+    // registry atomically (.tmp → rename, atomic on POSIX *and* Windows), so a
+    // reader always sees a complete prior-or-new file, never a partial one. A
+    // parse failure is therefore genuine corruption that re-reading the same
+    // bytes cannot fix, and a missing file (ENOENT, first run) is the expected
+    // "no registry yet" state. Either way we degrade gracefully to empty.
+    try {
+        const raw = readFileSync(registryPath(), "utf-8");
+        const data = JSON.parse(raw);
+        if (data && typeof data.by_path === "object")
+            return data;
+    }
+    catch {
+        /* ENOENT (no registry yet) or corrupt file — fall through to empty. */
+    }
+    return { by_path: {} };
+}
+/**
+ * Look up a project by its absolute path. Returns the entry or null.
+ * The path is normalised before lookup (backslashes → forward slashes,
+ * trailing slash stripped) so Windows CWD and GDScript registry keys match.
+ */
+export function lookupProject(projectPath) {
+    const key = normalizePath(projectPath);
+    const registry = readRegistry();
+    return registry.by_path[key] ?? null;
+}
+/**
+ * Return the runtime_port for a project, or null if no playtest is active.
+ * Re-reads the file on every call so newly-started playtests are picked up.
+ */
+export function discoverRuntime(projectPath) {
+    const entry = lookupProject(projectPath);
+    if (!entry)
+        return null;
+    const port = entry.runtime_port;
+    if (port == null || !Number.isInteger(port) || port < 1024 || port > 65535)
+        return null;
+    // Skip a port whose owning playtest process is provably dead. The toolkit has
+    // no PID-based GC (OS.is_process_running is unreliable on Windows), so a
+    // crashed playtest leaves runtime_port set until the next register() clears
+    // it; without this gate the bridge would attempt a doomed connect. A null
+    // runtime_pid (no recorded owner) does not block.
+    //
+    // A live PID is all this path asks for — deliberately weaker than the LSP
+    // claimant predicate below. A wrong runtime port announces itself (the connect
+    // fails into a visible GAME_NOT_RUNNING, and the channel has its own
+    // per-instance auth handshake), whereas a wrong LSP port silently returns
+    // another project's symbols; and this runs on every runtime RPC, not once per
+    // connection, so a socket probe here would tax the whole game_* surface.
+    if (entry.runtime_pid != null && !isPidAlive(entry.runtime_pid))
+        return null;
+    return port;
+}
+// -- LSP endpoint discovery --------------------------------------------------
+//
+// Godot's GDScript LSP binds one machine-wide port (default 6005); the toolkit
+// publishes each editor's setting-derived endpoint into its registry entry.
+// We resolve per-project and detect collisions server-side (the toolkit can't
+// read whether its own bind won). See lsp/lspClient.ts (resolveLspEndpoint).
+/**
+ * Every editor still credibly claiming a given LSP port — all of them, not just
+ * the newest.
+ *
+ * A claimant counts only when it is **pid-alive AND the WS command port its own
+ * entry advertises does not refuse a connection**. The PID check comes first
+ * because it is free and settles the provably-dead entries; the port probe is what
+ * establishes *identity*, since the projection never prunes cross-project entries and
+ * they all default to the same engine LSP port — so a stale entry whose recorded
+ * PID has been recycled to any unrelated process would otherwise resurrect a
+ * closed editor as a rival claimant. An inconclusive probe leaves the claimant
+ * counted — `registryLiveness.classifyProbeOutcome` carries why that direction is
+ * the safe one. Probes run concurrently, so the added latency is one round trip,
+ * not one per candidate.
+ */
+export async function liveLspClaimants(port) {
+    const registry = readRegistry();
+    const candidates = [];
+    for (const [path, entry] of Object.entries(registry.by_path)) {
+        if (entry.lsp_port !== port)
+            continue;
+        if (!isPidAlive(entry.pid))
+            continue;
+        candidates.push({ path, entry });
+    }
+    const notRefused = await Promise.all(candidates.map((c) => wsPortNotRefused(c.entry.port)));
+    return candidates.filter((_, i) => notRefused[i]);
+}
+/**
+ * Resolve this project's published LSP endpoint, with conservative ownership.
+ *   { host, port } — we own it: connect (then verify rootUri on 4.5+).
+ *   { conflict, port } — a corroborated peer started at-or-before us holds the port.
+ *   null — no usable entry; the caller applies the miss rule (conditional 6005).
+ *
+ * Connect only if strictly the EARLIEST corroborated claimant: the engine gives
+ * the port to whoever listen()s first, and started_at is a safe proxy for starts
+ * >~1s apart. A genuine same-second tie fails BOTH sides — never wrong data.
+ */
+export async function discoverLspEndpoint(projectPath) {
+    const entry = lookupProject(projectPath);
+    if (!entry || entry.lsp_port == null)
+        return null;
+    const port = entry.lsp_port;
+    const claimants = await liveLspClaimants(port);
+    const peers = claimants.filter((c) => c.entry.pid !== entry.pid);
+    if (peers.some((c) => c.entry.started_at <= entry.started_at))
+        return { conflict: true, port };
+    return { host: entry.lsp_host ?? "127.0.0.1", port };
+}
+// -- Registry watcher ----------------------------------------------------------
+//
+// Watches projects.json via fs.watch and fires callbacks when a project's
+// runtime_port transitions (null→port, port→null, port→different port).
+// Replaces per-RPC file reads with in-memory lookups when active.
+//
+// Safety net: a 30s stat-poll heartbeat catches silent watcher death (rare),
+// inode replacement on Linux/macOS, and the file-not-yet-created case (P2).
+let watcher = undefined;
+let cachedRegistry = { by_path: {} };
+let runtimeDiscoveredCb = undefined;
+let runtimeRemovedCb = undefined;
+let debounceTimer;
+let heartbeatTimer = undefined;
+let lastKnownMtimeMs = 0;
+function diffAndNotify(cached, fresh) {
+    const allKeys = new Set([...Object.keys(cached.by_path), ...Object.keys(fresh.by_path)]);
+    for (const key of allKeys) {
+        const oldPort = cached.by_path[key]?.runtime_port ?? null;
+        const newPort = fresh.by_path[key]?.runtime_port ?? null;
+        if (oldPort === newPort)
+            continue;
+        // Tear down before connect so the bridge never holds two channels
+        // to the same project simultaneously (important for port-change).
+        if (oldPort != null && oldPort > 0) {
+            runtimeRemovedCb?.(key);
+        }
+        if (newPort != null && newPort > 0) {
+            runtimeDiscoveredCb?.(key, newPort);
+        }
+    }
+}
+/** Debounced handler shared by fs.watch and heartbeat-triggered re-watches. */
+function handleRegistryChange() {
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+        const fresh = readRegistry();
+        diffAndNotify(cachedRegistry, fresh);
+        cachedRegistry = fresh;
+        // Sync mtime so the heartbeat doesn't re-fire for this same change.
+        try {
+            lastKnownMtimeMs = statSync(registryPath()).mtimeMs;
+        }
+        catch {
+            /* file may have been deleted — heartbeat handles it */
+        }
+    }, 100);
+}
+function onWatchError() {
+    watcher?.close();
+    watcher = undefined;
+}
+/** Try to establish (or re-establish) fs.watch on projects.json. */
+function tryStartWatcher() {
+    if (watcher)
+        return true;
+    try {
+        watcher = watch(registryPath(), { persistent: false }, handleRegistryChange);
+        watcher.on("error", onWatchError);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 30s stat-poll heartbeat. Covers:
+ *  - Silent watcher death (all platforms, rare)
+ *  - Inode replacement on Linux/macOS (file replaced via atomic rename)
+ *  - File not yet created at startup (P2) — retries watcher start
+ */
+function startHeartbeat() {
+    try {
+        lastKnownMtimeMs = statSync(registryPath()).mtimeMs;
+    }
+    catch {
+        /* file may not exist yet */
+    }
+    heartbeatTimer = setInterval(() => {
+        // Re-establish watcher if it died or never started (P2: ENOENT at init).
+        if (!watcher)
+            tryStartWatcher();
+        try {
+            const mtime = statSync(registryPath()).mtimeMs;
+            if (mtime !== lastKnownMtimeMs) {
+                lastKnownMtimeMs = mtime;
+                // Watcher missed this change — force re-read and diff.
+                const fresh = readRegistry();
+                diffAndNotify(cachedRegistry, fresh);
+                cachedRegistry = fresh;
+            }
+        }
+        catch {
+            // File gone — if we had entries, treat as full removal.
+            if (Object.keys(cachedRegistry.by_path).length > 0) {
+                const fresh = { by_path: {} };
+                diffAndNotify(cachedRegistry, fresh);
+                cachedRegistry = fresh;
+            }
+        }
+    }, 30_000);
+    heartbeatTimer.unref?.();
+}
+/**
+ * Start watching projects.json for runtime port changes.
+ *
+ * Falls back silently when fs.watch is unavailable or the file doesn't
+ * exist yet — isWatcherActive() returns false and callRuntime uses
+ * per-RPC file reads. The heartbeat retries watcher creation every 30s.
+ */
+export function watchRegistry(callbacks) {
+    runtimeDiscoveredCb = callbacks.onDiscovered;
+    runtimeRemovedCb = callbacks.onRemoved;
+    cachedRegistry = readRegistry();
+    tryStartWatcher();
+    startHeartbeat();
+}
+/** Stop watching and clean up. Safe to call even if never started. */
+export function unwatchRegistry() {
+    clearTimeout(debounceTimer);
+    if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = undefined;
+    }
+    watcher?.close();
+    watcher = undefined;
+}
+/** True when fs.watch is active and cachedRegistry is kept fresh. */
+export function isWatcherActive() {
+    return watcher !== undefined;
+}
+/**
+ * Read runtime_port from the in-memory cache (zero I/O).
+ * Returns null if no runtime is registered or the watcher hasn't seen one.
+ */
+export function getCachedRuntimePort(projectPath) {
+    const key = normalizePath(projectPath);
+    return cachedRegistry.by_path[key]?.runtime_port ?? null;
+}

package/dist/registryLiveness.js

@@ -0,0 +1,113 @@
+/**
+ * Liveness corroboration for registry entries.
+ *
+ * Answers one question about a `projects.json` entry: is the process it recorded
+ * still the editor that wrote it? A PID existence check alone cannot say — PIDs
+ * are a bounded, recycled resource, so a dead editor's leftover entry looks live
+ * the moment its number is handed to some unrelated process. The corroboration is
+ * the entry's own advertised WebSocket command port: a closed editor is not
+ * listening there, and a recycled PID cannot fake it.
+ *
+ * Deliberately knows nothing about the registry schema — it takes plain numbers,
+ * so the reader depends on it and never the reverse.
+ *
+ * @module
+ */
+import { createConnection } from "node:net";
+/** The toolkit's WebSocket command server binds loopback only. */
+const PROBE_HOST = "127.0.0.1";
+/**
+ * Corroboration probe budget. A loopback `ECONNREFUSED` returns in single-digit
+ * milliseconds, so this is ~30x headroom that still bounds the worst case: the
+ * probe sits on the once-per-connection LSP resolution path.
+ */
+const PROBE_TIMEOUT_MS = 300;
+/**
+ * Whether a process is still alive. Returns false only if provably dead.
+ *
+ * Signal 0 is a no-op "existence probe" — never delivered, it only tests whether
+ * the process exists and is signalable. Reliable on Linux, macOS AND Windows
+ * (Node/libuv maps it to OpenProcess on Windows, not the unreliable mechanism
+ * behind GDScript's OS.is_process_running). Outcomes:
+ *   - success            → the process exists                          → ALIVE
+ *   - throw ESRCH        → no such process                             → dead
+ *   - throw EPERM/EACCES → the process EXISTS but we may not signal it
+ *                          (another user / elevated / protected)       → ALIVE
+ *
+ * Treating EPERM/EACCES as alive is the POSIX-standard robust check (`kill(pid,0)`
+ * sets EPERM precisely *because* the target exists). It never triggers for our
+ * same-user sibling editors, but it keeps a cross-user/elevated peer from being
+ * mis-counted as dead on any platform.
+ *
+ * A live PID proves only that *some* signalable process holds that number — not
+ * that it is a Godot editor, and not that it is the editor of record. Pair it
+ * with {@link wsPortNotRefused} whenever identity matters.
+ */
+export function isPidAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        return code === "EPERM" || code === "EACCES";
+    }
+}
+/**
+ * The fail-closed policy for a corroboration probe, as a pure decision.
+ *
+ * `ECONNREFUSED` is the only positive proof of refusal — nothing is listening, so
+ * the editor that advertised the port is gone. Every other outcome (a timeout, a
+ * local resource limit, an unrecognised code) says nothing about the peer, and
+ * the two failure directions are not symmetric: treating an inconclusive probe as
+ * proof of death would drop a genuine rival and silently serve another project's
+ * data on Godot 4.2–4.4, which have no root-mismatch backstop. Calling it
+ * indeterminate keeps the peer counted, which is at worst today's visible
+ * behaviour — never worse.
+ *
+ * @param code the socket error's `code`, or undefined when the probe timed out
+ */
+export function classifyProbeOutcome(code) {
+    return code === "ECONNREFUSED" ? "dead" : "indeterminate";
+}
+/**
+ * Whether a connection to `port` was **not** positively refused.
+ *
+ * Named for what it actually establishes. `false` means `ECONNREFUSED` — proof the
+ * advertised port has no listener. `true` lumps a successful connect together with
+ * every inconclusive outcome ({@link classifyProbeOutcome}), and a port outside the
+ * connectable range cannot be probed at all, so `true` is the *absence of proof of
+ * death*, never proof of life. Reading it as "the port answered" would invert the
+ * fail-closed policy this predicate exists to implement.
+ *
+ * The socket closes with a graceful FIN rather than a reset: the toolkit wraps
+ * every accepted stream in a `WebSocketPeer` and logs `accept_stream failed` when
+ * the stream dies before the wrap, which would put probe noise in a real editor's
+ * Output dock.
+ */
+export function wsPortNotRefused(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65_535)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        const socket = createConnection({ host: PROBE_HOST, port });
+        let settled = false;
+        const settle = (responds, graceful) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (graceful)
+                socket.end();
+            else
+                socket.destroy();
+            resolve(responds);
+        };
+        const timer = setTimeout(() => settle(true, false), PROBE_TIMEOUT_MS);
+        socket.on("connect", () => settle(true, true));
+        // Listen (not once) so a late error after settling is absorbed here instead
+        // of surfacing as an unhandled 'error' event.
+        socket.on("error", (err) => settle(classifyProbeOutcome(err.code) !== "dead", false));
+    });
+}