gdharness 0.4.2 → 0.5.1

package/build/index.js

@@ -9802,11 +9802,332 @@ var require_websocket_server = __commonJS(function(exports, module) {
   }
 });
 
+// src/issues.ts
+import { createHash } from "node:crypto";
+import process2 from "node:process";
+
+// src/errors.ts
+class Refusal extends Error {
+}
+function errorMessage(error, fallback = "Unknown error") {
+  if (error instanceof Error) {
+    return error.message || fallback;
+  }
+  if (typeof error === "string") {
+    return error || fallback;
+  }
+  if (typeof error === "number" || typeof error === "boolean") {
+    return String(error);
+  }
+  return fallback;
+}
+function toError(error) {
+  return error instanceof Error ? error : new Error(errorMessage(error), { cause: error });
+}
+
+// src/server-version.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+
+// src/update-check.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+// src/runner.ts
+function currentRunner() {
+  const versions = process.versions;
+  return versions["bun"] === undefined ? "npx" : "bunx";
+}
+function runLine(runner, version, rest = "") {
+  const flag = runner === "npx" ? "-y " : "";
+  return `${runner} ${flag}gdharness@${version}${rest === "" ? "" : ` ${rest}`}`;
+}
+
+// src/update-check.ts
+var REGISTRY = "https://registry.npmjs.org/gdharness/latest";
+var RELEASES = "https://github.com/Aureliolo/gdharness/releases/tag";
+var CACHE_MS = 4 * 60 * 60 * 1000;
+var REQUEST_TIMEOUT_MS = 1e4;
+var MAX_BODY_BYTES = 1 << 20;
+var FIRST_RETRY_MS = 30000;
+var MAX_RETRY_MS = 60 * 60 * 1000;
+var VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+function cacheDirectory(environment) {
+  const set = (name) => {
+    const value = environment[name];
+    return value !== undefined && value !== "" ? value : null;
+  };
+  const home = set("HOME") ?? homedir();
+  if (process.platform === "win32") {
+    return join(set("LOCALAPPDATA") ?? home, "gdharness");
+  }
+  if (process.platform === "darwin") {
+    return join(home, "Library", "Caches", "gdharness");
+  }
+  return join(set("XDG_CACHE_HOME") ?? join(home, ".cache"), "gdharness");
+}
+function cacheFile(environment = process.env) {
+  try {
+    const directory = cacheDirectory(environment);
+    mkdirSync(directory, { recursive: true, mode: 448 });
+    return join(directory, "update-check.json");
+  } catch {
+    return join(tmpdir(), "gdharness-update-check.json");
+  }
+}
+function readCache(path) {
+  try {
+    if (!existsSync(path)) {
+      return null;
+    }
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) {
+      return null;
+    }
+    const record = parsed;
+    const checkedAt = record["checkedAt"];
+    const latest = record["latest"];
+    if (typeof checkedAt !== "number" || typeof latest !== "string" || !VERSION.test(latest)) {
+      return null;
+    }
+    return { checkedAt, latest };
+  } catch {
+    return null;
+  }
+}
+function writeCache(path, entry) {
+  try {
+    writeFileSync(path, JSON.stringify(entry), { encoding: "utf8", mode: 384 });
+  } catch {}
+}
+function parts(version) {
+  const withoutBuild = version.split("+")[0] ?? version;
+  const dash = withoutBuild.indexOf("-");
+  const numeric = dash === -1 ? withoutBuild : withoutBuild.slice(0, dash);
+  return {
+    numbers: numeric.split(".").map((piece) => Number.parseInt(piece, 10) || 0),
+    prerelease: dash !== -1
+  };
+}
+function isNewer(candidate, current) {
+  const left = parts(candidate);
+  const right = parts(current);
+  for (let index = 0;index < 3; index += 1) {
+    const a = left.numbers[index] ?? 0;
+    const b = right.numbers[index] ?? 0;
+    if (a !== b) {
+      return a > b;
+    }
+  }
+  return !left.prerelease && right.prerelease;
+}
+async function fetchLatest() {
+  const response = await fetch(REGISTRY, {
+    headers: { accept: "application/vnd.npm.install-v1+json, application/json" },
+    redirect: "error",
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (!response.ok || response.body === null) {
+    return null;
+  }
+  const declared = Number.parseInt(response.headers.get("content-length") ?? "", 10);
+  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+    return null;
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of response.body) {
+    size += chunk.byteLength;
+    if (size > MAX_BODY_BYTES) {
+      return null;
+    }
+    chunks.push(chunk);
+  }
+  const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  if (typeof parsed !== "object" || parsed === null) {
+    return null;
+  }
+  const version = parsed["version"];
+  return typeof version === "string" && VERSION.test(version) ? version : null;
+}
+
+class UpdateCheck {
+  latest = null;
+  checking = false;
+  checkedAt = 0;
+  retryAt = 0;
+  backoffMs = FIRST_RETRY_MS;
+  enabled;
+  current;
+  cachePath;
+  constructor(current, environment = process.env) {
+    this.current = current;
+    this.enabled = (environment["GDHARNESS_NO_UPDATE_CHECK"] ?? "") === "";
+    this.cachePath = cacheFile(environment);
+    const cached = this.enabled ? readCache(this.cachePath) : null;
+    if (cached !== null) {
+      this.latest = cached.latest;
+      this.checkedAt = cached.checkedAt;
+    }
+  }
+  refresh(now = Date.now()) {
+    if (!this.enabled || this.checking || now < this.retryAt || now - this.checkedAt < CACHE_MS) {
+      return;
+    }
+    this.checking = true;
+    fetchLatest().then((version) => {
+      if (version === null) {
+        this.scheduleRetry(now);
+        return;
+      }
+      this.latest = version;
+      this.checkedAt = Date.now();
+      this.backoffMs = FIRST_RETRY_MS;
+      this.retryAt = 0;
+      writeCache(this.cachePath, { checkedAt: this.checkedAt, latest: version });
+    }).catch(() => {
+      this.scheduleRetry(now);
+    }).finally(() => {
+      this.checking = false;
+    });
+  }
+  scheduleRetry(now) {
+    this.retryAt = now + this.backoffMs;
+    this.backoffMs = Math.min(this.backoffMs * 2, MAX_RETRY_MS);
+  }
+  notice() {
+    const latest = this.latest;
+    if (!this.enabled || latest === null || !isNewer(latest, this.current)) {
+      return null;
+    }
+    return {
+      current: this.current,
+      latest,
+      releaseNotes: `${RELEASES}/v${latest}`,
+      upgrade: runLine(currentRunner(), latest, "upgrade")
+    };
+  }
+}
+
+// src/server-version.ts
+var DEBUG_MODE = process.env["DEBUG"] === "true";
+var GODOT_DEBUG_MODE_DEFAULT = process.env["GODOT_DEBUG"] === "true" || DEBUG_MODE;
+var SERVER_VERSION = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+var UNVERSIONED = "addon from before versions were reported";
+function addonMismatch(addonVersion, serverVersion) {
+  if (addonVersion === serverVersion) {
+    return;
+  }
+  const reported = addonVersion ?? "";
+  const editor = reported === "" ? UNVERSIONED : reported;
+  const both = `The editor is running the ${editor} addon while this server ships ${serverVersion}.`;
+  if (reported !== "" && isNewer(reported, serverVersion)) {
+    return `${both} This server is the older half: reconnect it in your harness so it spawns ${reported}.`;
+  }
+  return `${both} Restart it with editor_launch restart to pick the new one up.`;
+}
+
+// src/issues.ts
+var NEW_ISSUE = "https://github.com/Aureliolo/gdharness/issues/new";
+var ENHANCEMENT_URL = `${NEW_ISSUE}?template=feature_request.md`;
+function runtime() {
+  const versions = process2.versions;
+  const bun = versions["bun"];
+  return bun === undefined ? `node ${process2.versions.node}` : `bun ${bun}`;
+}
+function defectSignature(where, message) {
+  const normalised = `${where}
+${message}`.toLowerCase().replaceAll("\\", "/").replaceAll(/(?:[a-z]:)?(?:\/+[\w.-]+){2,}/gu, "<path>").replaceAll(/\d+/gu, "0");
+  return createHash("sha256").update(normalised).digest("hex").slice(0, 8);
+}
+function facts(where, message, godotVersion) {
+  return [
+    ["Where", where],
+    ["Error", message],
+    ["Version", `gdharness ${SERVER_VERSION}`],
+    ["Runtime", `${runtime()}, ${process2.platform} ${process2.arch}`],
+    ["Godot", godotVersion ?? "not known at the point this failed"],
+    ["Signature", defectSignature(where, message)]
+  ];
+}
+function filledTemplate(where, message, godotVersion) {
+  return [
+    `**gdharness version**: ${SERVER_VERSION}`,
+    `**Godot version**: ${godotVersion ?? ""}`,
+    `**Bun version**: ${runtime()}`,
+    `**OS**: ${process2.platform} ${process2.arch}`,
+    "**MCP client**:",
+    "",
+    "## What you did",
+    "",
+    where,
+    "",
+    "## What you expected",
+    "",
+    "The call to answer, or to refuse with a reason.",
+    "",
+    "## What happened",
+    "",
+    "gdharness failed in a way it does not model.",
+    "",
+    "```text",
+    message,
+    "```",
+    "",
+    `Signature: \`${defectSignature(where, message)}\``,
+    "",
+    "If the real cause turned out to be the project, the environment or the call, say so here:",
+    "reaching you as a defect rather than as a refusal naming what would have worked is then the",
+    "thing to fix.",
+    "",
+    "## Anything that makes it reproducible",
+    ""
+  ].join(`
+`);
+}
+function defectReport(where, error, godotVersion) {
+  const message = errorMessage(error);
+  const title = `Defect ${defectSignature(where, message)}: ${where}`;
+  const url = `${NEW_ISSUE}?template=bug_report.md&title=${encodeURIComponent(title)}` + `&body=${encodeURIComponent(filledTemplate(where, message, godotVersion))}`;
+  const width = Math.max(...facts(where, message, godotVersion).map(([label]) => (label ?? "").length));
+  return [
+    "gdharness failed in a way it does not model. This is a defect in gdharness rather than",
+    "anything about the call: the arguments did not cause it, and sending it again will not",
+    "change it.",
+    "",
+    ...facts(where, message, godotVersion).map(([label, value]) => `  ${(label ?? "").padEnd(width)}  ${value ?? ""}`),
+    "",
+    "Do not open an issue on your own initiative. Tell the person whose machine this is what",
+    "broke, and ask whether you may report it to gdharness on their behalf. What the report",
+    "carries is the lines above and nothing else, and whether that goes into a public tracker",
+    "is theirs to decide.",
+    "",
+    "If they say yes, this link carries the report already filled in:",
+    url,
+    "",
+    "If they say yes and you have no way to open an issue yourself, give them that link and",
+    "those lines, and stay with them while they file it.",
+    "",
+    "Worth reporting either way. If you can see that what actually went wrong was the project,",
+    "the environment or the call, then this message is the defect: a failure gdharness knows",
+    "about is meant to arrive as a refusal naming what would have worked, not as this. Say that",
+    "in the report and it is the more useful of the two."
+  ].join(`
+`);
+}
+
 // src/server.ts
 import { execFile as execFile3, spawn } from "node:child_process";
-import { existsSync as existsSync4, mkdtempSync as mkdtempSync2, readdirSync as readdirSync4, readFileSync as readFileSync5, realpathSync as realpathSync2, rmSync as rmSync2 } from "node:fs";
-import { tmpdir as tmpdir3 } from "node:os";
-import { basename, dirname as dirname2, join as join5, normalize as normalize2 } from "node:path";
+import { existsSync as existsSync6, mkdtempSync as mkdtempSync2, readdirSync as readdirSync5, readFileSync as readFileSync7, realpathSync as realpathSync2, rmSync as rmSync2 } from "node:fs";
+import { tmpdir as tmpdir4 } from "node:os";
+import { basename, dirname as dirname2, join as join7, normalize as normalize2 } from "node:path";
 import { setTimeout as delay2 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { promisify as promisify3 } from "node:util";
@@ -24269,7 +24590,7 @@ var EMPTY_COMPLETION_RESULT = {
 };
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
-import process2 from "node:process";
+import process3 from "node:process";
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
 var STDIO_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
@@ -24313,7 +24634,7 @@ function serializeMessage(message) {
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 class StdioServerTransport {
-  constructor(_stdin = process2.stdin, _stdout = process2.stdout, options) {
+  constructor(_stdin = process3.stdin, _stdout = process3.stdout, options) {
     this._stdin = _stdin;
     this._stdout = _stdout;
     this._started = false;
@@ -24374,6 +24695,50 @@ class StdioServerTransport {
   }
 }
 
+// src/class-cache.ts
+import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync3 } from "node:fs";
+import { join as join2 } from "node:path";
+function declaredClasses(projectPath) {
+  const declared = new Map;
+  const visit = (directory, prefix) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+      const path = join2(directory, entry.name);
+      if (entry.isDirectory()) {
+        visit(path, `${prefix}${entry.name}/`);
+      } else if (entry.isFile() && entry.name.endsWith(".gd")) {
+        const found = /^class_name\s+([A-Za-z_][A-Za-z0-9_]*)/m.exec(readFileSync3(path, "utf8"));
+        if (found?.[1]) {
+          declared.set(found[1], `res://${prefix}${entry.name}`);
+        }
+      }
+    }
+  };
+  visit(projectPath, "");
+  return declared;
+}
+function cachedClasses(projectPath) {
+  const cache = join2(projectPath, ".godot", "global_script_class_cache.cfg");
+  if (!existsSync2(cache)) {
+    return null;
+  }
+  const listed = new Map;
+  const text = readFileSync3(cache, "utf8");
+  for (const entry of text.matchAll(/"class":\s*&"([^"]+)"[\s\S]*?"path":\s*"([^"]+)"/g)) {
+    listed.set(entry[1] ?? "", entry[2] ?? "");
+  }
+  return listed;
+}
+function staleAgainst(cached, projectPath) {
+  return [...declaredClasses(projectPath)].filter(([name, path]) => cached.get(name) !== path).map(([name]) => name);
+}
+function staleClassNames(projectPath) {
+  const cached = cachedClasses(projectPath);
+  return cached === null ? [...declaredClasses(projectPath).keys()] : staleAgainst(cached, projectPath);
+}
+
 // src/dap_client.ts
 import { createConnection } from "node:net";
 import { setTimeout as delay } from "node:timers/promises";
@@ -24464,7 +24829,7 @@ function portFromEnv(variable, fallback) {
   }
   const parsed = Number.parseInt(raw, 10);
   if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535 || String(parsed) !== raw) {
-    throw new Error(`${variable} is "${raw}", not a port between 1 and 65535.`);
+    throw new Refusal(`${variable} is "${raw}", not a port between 1 and 65535.`);
   }
   return parsed;
 }
@@ -24488,6 +24853,7 @@ class GodotDAPClient {
   initialized = false;
   attached = false;
   lastThreadId = 1;
+  stopped = false;
   breakpoints = new Map;
   constructor(port = portFromEnv("GDHARNESS_DAP_PORT", DEFAULT_DAP_PORT), host = "127.0.0.1") {
     this.port = port;
@@ -24536,6 +24902,7 @@ class GodotDAPClient {
           this.connected = false;
           this.initialized = false;
           this.attached = false;
+          this.stopped = false;
           this.socket = null;
           this.failPendingRequests(new Error("DAP connection closed"));
         });
@@ -24555,6 +24922,7 @@ class GodotDAPClient {
       this.connected = false;
       this.initialized = false;
       this.attached = false;
+      this.stopped = false;
       return;
     }
     if (this.connected) {
@@ -24583,6 +24951,7 @@ class GodotDAPClient {
     this.connected = false;
     this.initialized = false;
     this.attached = false;
+    this.stopped = false;
   }
   async ensureConnected() {
     if (!this.connected) {
@@ -24592,7 +24961,7 @@ class GodotDAPClient {
   async sendRequest(command, args, timeoutMs = DAP_REQUEST_TIMEOUT_MS) {
     await this.ensureConnected();
     if (!this.socket) {
-      throw new Error("DAP socket is not available");
+      throw new Refusal("DAP socket is not available");
     }
     const requestSeq = this.seq++;
     const request = {
@@ -24659,10 +25028,12 @@ class GodotDAPClient {
       if (typeof threadId === "number") {
         this.lastThreadId = threadId;
       }
+      this.stopped = true;
       return;
     }
     if (eventName === "terminated" || eventName === "exited") {
       this.attached = false;
+      this.stopped = false;
     }
   }
   async initialize() {
@@ -24736,6 +25107,7 @@ class GodotDAPClient {
     await this.attach();
     const resolvedThreadId = await this.resolveThreadId(threadId);
     await this.sendRequest("continue", { threadId: resolvedThreadId });
+    this.stopped = false;
   }
   async stepOver(threadId) {
     await this.attach();
@@ -24805,6 +25177,9 @@ class GodotDAPClient {
   isConnected() {
     return this.connected;
   }
+  isStopped() {
+    return this.stopped;
+  }
   async resolveThreadId(threadId) {
     if (typeof threadId === "number" && threadId > 0) {
       this.lastThreadId = threadId;
@@ -24832,6 +25207,7 @@ class GodotDAPClient {
     this.connected = false;
     this.initialized = false;
     this.attached = false;
+    this.stopped = false;
     this.reader = new FrameReader;
     socket?.destroy();
     this.failPendingRequests(new Error(`Godot DAP ${detail}. The connection was dropped.`));
@@ -24856,7 +25232,7 @@ async function handleDAPTool(client, toolName, args) {
       }
       case "dap_set_breakpoint": {
         if (typeof safeArgs.scriptPath !== "string" || typeof safeArgs.line !== "number") {
-          throw new Error("dap_set_breakpoint requires { scriptPath: string, line: number }");
+          throw new Refusal("dap_set_breakpoint requires { scriptPath: string, line: number }");
         }
         const result = await client.setBreakpoint(safeArgs.scriptPath, safeArgs.line);
         return {
@@ -24865,7 +25241,7 @@ async function handleDAPTool(client, toolName, args) {
       }
       case "dap_remove_breakpoint": {
         if (typeof safeArgs.scriptPath !== "string" || typeof safeArgs.line !== "number") {
-          throw new Error("dap_remove_breakpoint requires { scriptPath: string, line: number }");
+          throw new Refusal("dap_remove_breakpoint requires { scriptPath: string, line: number }");
         }
         const result = await client.removeBreakpoint(safeArgs.scriptPath, safeArgs.line);
         return {
@@ -24930,23 +25306,6 @@ function dictionary(entries) {
   return Object.assign(emptyRecord(), entries);
 }
 
-// src/errors.ts
-function errorMessage(error, fallback = "Unknown error") {
-  if (error instanceof Error) {
-    return error.message || fallback;
-  }
-  if (typeof error === "string") {
-    return error || fallback;
-  }
-  if (typeof error === "number" || typeof error === "boolean") {
-    return String(error);
-  }
-  return fallback;
-}
-function toError(error) {
-  return error instanceof Error ? error : new Error(errorMessage(error), { cause: error });
-}
-
 // src/game-log.ts
 import { StringDecoder } from "node:string_decoder";
 var HEADLINE = /^(USER )?(SCRIPT ERROR|ERROR|WARNING):\s?(.*)$/;
@@ -25350,7 +25709,7 @@ class GodotBridge extends EventEmitter {
   }
   sendMessage(message) {
     if (this.socket?.readyState !== import_websocket.default.OPEN) {
-      throw new Error("Godot is not connected");
+      throw new Refusal("Godot is not connected");
     }
     this.socket.send(JSON.stringify(message));
   }
@@ -25458,28 +25817,28 @@ function getDefaultBridge() {
 
 // src/godot-path.ts
 import { execFile } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync4 } from "node:fs";
 import { normalize } from "node:path";
 import { promisify } from "node:util";
 
 // src/detection.ts
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { existsSync as existsSync3, readdirSync as readdirSync2, statSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join3 } from "node:path";
 function resolveHomeDirectory() {
   try {
-    return homedir();
+    return homedir2();
   } catch {
     return "";
   }
 }
 function scanDirectoryForGodotBinaries(directory, platform) {
-  if (!directory || !existsSync(directory)) {
+  if (!directory || !existsSync3(directory)) {
     return [];
   }
   let entries;
   try {
-    entries = readdirSync(directory);
+    entries = readdirSync2(directory);
   } catch {
     return [];
   }
@@ -25489,7 +25848,7 @@ function scanDirectoryForGodotBinaries(directory, platform) {
     if (!pattern.test(name)) {
       continue;
     }
-    const fullPath = join(directory, name);
+    const fullPath = join3(directory, name);
     try {
       const stat = statSync(fullPath);
       if (stat.isFile()) {
@@ -25498,7 +25857,7 @@ function scanDirectoryForGodotBinaries(directory, platform) {
     } catch {}
   }
   matches.sort((a, b) => b.mtime - a.mtime);
-  return matches.map((m) => join(directory, m.name));
+  return matches.map((m) => join3(directory, m.name));
 }
 function conventionalPaths(platform, home) {
   const paths = ["godot"];
@@ -25613,7 +25972,7 @@ class GodotLocator {
       return known;
     }
     let ok = false;
-    if (path === "godot" || existsSync2(path)) {
+    if (path === "godot" || existsSync4(path)) {
       try {
         await run(path, ["--version"]);
         ok = true;
@@ -25628,9 +25987,9 @@ class GodotLocator {
 
 // src/headless.ts
 import { execFile as execFile2 } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join as join2 } from "node:path";
+import { mkdtempSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join4 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 var run2 = promisify2(execFile2);
 function snakeCased(params) {
@@ -25671,9 +26030,9 @@ function reason(stdout, stderr) {
   return stdout.trim().split(/\r?\n/).at(-1) ?? "no output at all";
 }
 async function runOperation(engine, operation, params, projectPath) {
-  const paramsDir = mkdtempSync(join2(tmpdir(), "gdharness-params-"));
-  const paramsFile = join2(paramsDir, `${operation}.json`);
-  writeFileSync(paramsFile, JSON.stringify(snakeCased(params)), "utf8");
+  const paramsDir = mkdtempSync(join4(tmpdir2(), "gdharness-params-"));
+  const paramsFile = join4(paramsDir, `${operation}.json`);
+  writeFileSync2(paramsFile, JSON.stringify(snakeCased(params)), "utf8");
   const args = [
     "--headless",
     "--path",
@@ -25716,6 +26075,105 @@ async function runOperation(engine, operation, params, projectPath) {
   return { ok: true, payload, messages: problems(stderr) };
 }
 
+// src/issues.ts
+import { createHash as createHash2 } from "node:crypto";
+import process4 from "node:process";
+var NEW_ISSUE2 = "https://github.com/Aureliolo/gdharness/issues/new";
+var ENHANCEMENT_URL2 = `${NEW_ISSUE2}?template=feature_request.md`;
+function feedbackNotice() {
+  return JSON.stringify({
+    gdharness_feedback: {
+      what_to_do: "If this session has run into something gdharness cannot do, or a tool that should " + "exist and does not, tell the user what is missing and offer to open an enhancement " + "issue for them. Only if they say yes, and only for a real gap: a call you got wrong " + "is not one. If you cannot open an issue yourself, give them the link and what to " + "write in it.",
+      enhancement_url: ENHANCEMENT_URL2
+    }
+  }, null, 2);
+}
+function runtime2() {
+  const versions = process4.versions;
+  const bun = versions["bun"];
+  return bun === undefined ? `node ${process4.versions.node}` : `bun ${bun}`;
+}
+function defectSignature2(where, message) {
+  const normalised = `${where}
+${message}`.toLowerCase().replaceAll("\\", "/").replaceAll(/(?:[a-z]:)?(?:\/+[\w.-]+){2,}/gu, "<path>").replaceAll(/\d+/gu, "0");
+  return createHash2("sha256").update(normalised).digest("hex").slice(0, 8);
+}
+function facts2(where, message, godotVersion) {
+  return [
+    ["Where", where],
+    ["Error", message],
+    ["Version", `gdharness ${SERVER_VERSION}`],
+    ["Runtime", `${runtime2()}, ${process4.platform} ${process4.arch}`],
+    ["Godot", godotVersion ?? "not known at the point this failed"],
+    ["Signature", defectSignature2(where, message)]
+  ];
+}
+function filledTemplate2(where, message, godotVersion) {
+  return [
+    `**gdharness version**: ${SERVER_VERSION}`,
+    `**Godot version**: ${godotVersion ?? ""}`,
+    `**Bun version**: ${runtime2()}`,
+    `**OS**: ${process4.platform} ${process4.arch}`,
+    "**MCP client**:",
+    "",
+    "## What you did",
+    "",
+    where,
+    "",
+    "## What you expected",
+    "",
+    "The call to answer, or to refuse with a reason.",
+    "",
+    "## What happened",
+    "",
+    "gdharness failed in a way it does not model.",
+    "",
+    "```text",
+    message,
+    "```",
+    "",
+    `Signature: \`${defectSignature2(where, message)}\``,
+    "",
+    "If the real cause turned out to be the project, the environment or the call, say so here:",
+    "reaching you as a defect rather than as a refusal naming what would have worked is then the",
+    "thing to fix.",
+    "",
+    "## Anything that makes it reproducible",
+    ""
+  ].join(`
+`);
+}
+function defectReport2(where, error, godotVersion) {
+  const message = errorMessage(error);
+  const title = `Defect ${defectSignature2(where, message)}: ${where}`;
+  const url = `${NEW_ISSUE2}?template=bug_report.md&title=${encodeURIComponent(title)}` + `&body=${encodeURIComponent(filledTemplate2(where, message, godotVersion))}`;
+  const width = Math.max(...facts2(where, message, godotVersion).map(([label]) => (label ?? "").length));
+  return [
+    "gdharness failed in a way it does not model. This is a defect in gdharness rather than",
+    "anything about the call: the arguments did not cause it, and sending it again will not",
+    "change it.",
+    "",
+    ...facts2(where, message, godotVersion).map(([label, value]) => `  ${(label ?? "").padEnd(width)}  ${value ?? ""}`),
+    "",
+    "Do not open an issue on your own initiative. Tell the person whose machine this is what",
+    "broke, and ask whether you may report it to gdharness on their behalf. What the report",
+    "carries is the lines above and nothing else, and whether that goes into a public tracker",
+    "is theirs to decide.",
+    "",
+    "If they say yes, this link carries the report already filled in:",
+    url,
+    "",
+    "If they say yes and you have no way to open an issue yourself, give them that link and",
+    "those lines, and stay with them while they file it.",
+    "",
+    "Worth reporting either way. If you can see that what actually went wrong was the project,",
+    "the environment or the call, then this message is the defect: a failure gdharness knows",
+    "about is meant to arrive as a refusal naming what would have worked, not as this. Say that",
+    "in the report and it is the more useful of the two."
+  ].join(`
+`);
+}
+
 // src/junit.ts
 class MalformedReportError extends Error {
   constructor(message) {
@@ -26083,7 +26541,7 @@ class GodotLSPClient {
   async sendRequest(method, params) {
     await this.ensureConnected();
     if (!this.socket) {
-      throw new Error("Not connected to Godot LSP");
+      throw new Refusal("Not connected to Godot LSP");
     }
     this.requestId += 1;
     const id = this.requestId;
@@ -26122,7 +26580,7 @@ class GodotLSPClient {
   }
   sendNotification(method, params) {
     if (!this.connected || !this.socket) {
-      throw new Error("Not connected to Godot LSP");
+      throw new Refusal("Not connected to Godot LSP");
     }
     const payload = {
       jsonrpc: "2.0",
@@ -26372,36 +26830,36 @@ async function resolveLSPPaths(projectPathValue, scriptPathValue) {
   try {
     projectPath = await realpath(requestedProjectPath);
   } catch {
-    throw new Error(`Project path does not exist: ${requestedProjectPath}`);
+    throw new Refusal(`Project path does not exist: ${requestedProjectPath}`);
   }
   const contained = resolveWithinProject(projectPath, scriptPathValue);
   if (!contained.ok) {
-    throw new Error(contained.reason);
+    throw new Refusal(contained.reason);
   }
   let scriptPath;
   try {
     scriptPath = await realpath(contained.absolutePath);
   } catch {
-    throw new Error(`Script file does not exist: ${contained.absolutePath}`);
+    throw new Refusal(`Script file does not exist: ${contained.absolutePath}`);
   }
   if (!isWithinRoot(projectPath, scriptPath)) {
-    throw new Error("scriptPath resolves outside the project root boundary.");
+    throw new Refusal("scriptPath resolves outside the project root boundary.");
   }
   return { projectPath, scriptPath };
 }
 async function handleLSPTool(client, toolName, args) {
   try {
     if (!args || typeof args !== "object") {
-      throw new Error("Tool arguments must be an object.");
+      throw new Refusal("Tool arguments must be an object.");
     }
     const parsedArgs = args;
     const projectPathValue = parsedArgs["projectPath"];
     const scriptPathValue = parsedArgs["scriptPath"];
     if (typeof projectPathValue !== "string" || projectPathValue.length === 0) {
-      throw new Error("Missing required argument: projectPath");
+      throw new Refusal("Missing required argument: projectPath");
     }
     if (typeof scriptPathValue !== "string" || scriptPathValue.length === 0) {
-      throw new Error("Missing required argument: scriptPath");
+      throw new Refusal("Missing required argument: scriptPath");
     }
     const { projectPath, scriptPath } = await resolveLSPPaths(projectPathValue, scriptPathValue);
     const content = await readFile(scriptPath, "utf8");
@@ -26415,7 +26873,7 @@ async function handleLSPTool(client, toolName, args) {
         const line = Number(parsedArgs["line"]);
         const character = Number(parsedArgs["character"]);
         if (!Number.isFinite(line) || !Number.isFinite(character)) {
-          throw new Error("Arguments line and character must be numbers.");
+          throw new Refusal("Arguments line and character must be numbers.");
         }
         const completions = await client.getCompletions(scriptPath, content, line, character);
         return asToolResponse({ completions });
@@ -26424,7 +26882,7 @@ async function handleLSPTool(client, toolName, args) {
         const line = Number(parsedArgs["line"]);
         const character = Number(parsedArgs["character"]);
         if (!Number.isFinite(line) || !Number.isFinite(character)) {
-          throw new Error("Arguments line and character must be numbers.");
+          throw new Refusal("Arguments line and character must be numbers.");
         }
         const hover = await client.getHover(scriptPath, content, line, character);
         return asToolResponse({ hover });
@@ -26444,19 +26902,19 @@ async function handleLSPTool(client, toolName, args) {
 }
 
 // src/project-scan.ts
-import { readdirSync as readdirSync2, readFileSync } from "node:fs";
-import { join as join3 } from "node:path";
+import { readdirSync as readdirSync3, readFileSync as readFileSync4 } from "node:fs";
+import { join as join5 } from "node:path";
 var SKIPPED = new Set([".git", ".godot", ".import", "node_modules"]);
 var ASSET_EXTENSIONS = new Set(["png", "jpg", "jpeg", "webp", "svg", "ttf", "otf", "wav", "mp3", "ogg"]);
 function projectStructure(projectPath) {
   const structure = { scenes: 0, scripts: 0, assets: 0, other: 0 };
   const visit = (directory) => {
-    for (const entry of readdirSync2(directory, { withFileTypes: true })) {
+    for (const entry of readdirSync3(directory, { withFileTypes: true })) {
       if (entry.name.startsWith(".")) {
         continue;
       }
       if (entry.isDirectory()) {
-        visit(join3(directory, entry.name));
+        visit(join5(directory, entry.name));
       } else if (entry.isFile()) {
         const extension = entry.name.split(".").pop()?.toLowerCase() ?? "";
         if (extension === "tscn") {
@@ -26491,14 +26949,14 @@ function searchProject(projectPath, options) {
     return false;
   };
   const visit = (directory) => {
-    for (const entry of readdirSync2(directory, { withFileTypes: true })) {
+    for (const entry of readdirSync3(directory, { withFileTypes: true })) {
       if (full()) {
         return;
       }
       if (SKIPPED.has(entry.name)) {
         continue;
       }
-      const entryPath = join3(directory, entry.name);
+      const entryPath = join5(directory, entry.name);
       if (entry.isDirectory()) {
         visit(entryPath);
         continue;
@@ -26509,7 +26967,7 @@ function searchProject(projectPath, options) {
       }
       result.summary.files_searched += 1;
       const matches = [];
-      for (const [index, line] of readFileSync(entryPath, "utf8").split(`
+      for (const [index, line] of readFileSync4(entryPath, "utf8").split(`
 `).entries()) {
         if (full()) {
           break;
@@ -26532,7 +26990,7 @@ function searchProject(projectPath, options) {
 }
 
 // src/resources.ts
-import { readFileSync as readFileSync2 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 import { extname, resolve as resolve3 } from "node:path";
 var STATIC_RESOURCES = [
   {
@@ -26562,24 +27020,25 @@ var RESOURCE_TEMPLATES = [
     mimeType: "text/plain"
   }
 ];
+var RESOURCE_COUNT = STATIC_RESOURCES.length + RESOURCE_TEMPLATES.length;
 function ensureProjectPath(getProjectPath) {
   const projectPath = getProjectPath();
   if (!projectPath) {
-    throw new Error("Project path is not set. Set a Godot project path first.");
+    throw new Refusal("Project path is not set. Set a Godot project path first.");
   }
   return resolve3(projectPath);
 }
 function uriPathToProjectPath(inputPath) {
   const normalized = inputPath.replace(/\\/g, "/").trim();
   if (normalized.replace(/\//g, "") === "") {
-    throw new Error("Resource path is empty.");
+    throw new Refusal("Resource path is empty.");
   }
   return normalized.replace(/^\/+/, "");
 }
 function resolveProjectFile(projectPath, resourcePath) {
   const contained = resolveWithinProject(projectPath, resourcePath);
   if (!contained.ok) {
-    throw new Error(contained.reason);
+    throw new Refusal(contained.reason);
   }
   return contained.absolutePath;
 }
@@ -26591,14 +27050,14 @@ function parseGodotUri(uri) {
   try {
     parsed = new URL(uri);
   } catch {
-    throw new Error(`Invalid URI: ${uri}`);
+    throw new Refusal(`Invalid URI: ${uri}`);
   }
   if (parsed.protocol !== "godot:") {
-    throw new Error(`Unsupported URI scheme: ${parsed.protocol}`);
+    throw new Refusal(`Unsupported URI scheme: ${parsed.protocol}`);
   }
   const host = parsed.hostname;
   if (host !== "scene" && host !== "script" && host !== "resource") {
-    throw new Error(`Unsupported Godot resource type: ${host}`);
+    throw new Refusal(`Unsupported Godot resource type: ${host}`);
   }
   const resourcePath = uriPathToProjectPath(decodeURIComponent(parsed.pathname));
   return { kind: host, resourcePath };
@@ -26606,13 +27065,13 @@ function parseGodotUri(uri) {
 function ensureAllowedExtension(kind, filePath) {
   const extension = extname(filePath).toLowerCase();
   if (kind === "scene" && extension !== ".tscn") {
-    throw new Error("Scene resources must use .tscn extension.");
+    throw new Refusal("Scene resources must use .tscn extension.");
   }
   if (kind === "script" && extension !== ".gd") {
-    throw new Error("Script resources must use .gd extension.");
+    throw new Refusal("Script resources must use .gd extension.");
   }
   if (kind === "resource" && ![".tres", ".tscn", ".gd"].includes(extension)) {
-    throw new Error("Resource URIs support only .tres, .tscn, and .gd files.");
+    throw new Refusal("Resource URIs support only .tres, .tscn, and .gd files.");
   }
 }
 function isValueComplete(value) {
@@ -26702,7 +27161,7 @@ function readResourceText(uri, getProjectPath) {
   const parsedUri = parseGodotUri(uri);
   if (parsedUri.kind === "project-info") {
     const projectFilePath = resolveProjectFile(projectPath, "project.godot");
-    const rawProject = readFileSync2(projectFilePath, "utf-8");
+    const rawProject = readFileSync5(projectFilePath, "utf-8");
     const parsedProject = parseProjectGodot(rawProject);
     return {
       mimeType: "application/json",
@@ -26711,7 +27170,7 @@ function readResourceText(uri, getProjectPath) {
   }
   const filePath = resolveProjectFile(projectPath, parsedUri.resourcePath);
   ensureAllowedExtension(parsedUri.kind, filePath);
-  const text = readFileSync2(filePath, "utf-8");
+  const text = readFileSync5(filePath, "utf-8");
   return {
     mimeType: parsedUri.kind === "script" ? "text/x-gdscript" : "text/plain",
     text
@@ -26740,18 +27199,18 @@ function setupResourceHandlers(mcp, getProjectPath) {
       };
     } catch (error) {
       if (error instanceof Error) {
-        throw new Error(`Failed to read resource '${uri}': ${error.message}`, { cause: error });
+        throw new Refusal(`Failed to read resource '${uri}': ${error.message}`, { cause: error });
       }
-      throw new Error(`Failed to read resource '${uri}'.`, { cause: error });
+      throw new Refusal(`Failed to read resource '${uri}'.`, { cause: error });
     }
   });
 }
 
 // src/runtime-client.ts
-import { existsSync as existsSync3, readdirSync as readdirSync3, readFileSync as readFileSync3, unlinkSync } from "node:fs";
+import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync6, unlinkSync } from "node:fs";
 import { createConnection as createConnection3 } from "node:net";
-import { tmpdir as tmpdir2 } from "node:os";
-import { join as join4, resolve as resolve4 } from "node:path";
+import { tmpdir as tmpdir3 } from "node:os";
+import { join as join6, resolve as resolve4 } from "node:path";
 
 // src/tool-args.ts
 function asParams(value) {
@@ -26813,7 +27272,15 @@ function runtimeDirectory(variables = process.env) {
     return explicit;
   }
   const perUser = envValue("XDG_RUNTIME_DIR", variables);
-  return join4(perUser ?? tmpdir2(), "gdharness");
+  return join6(perUser ?? tmpdir3(), "gdharness");
+}
+function runtimeDirectories(variables = process.env) {
+  const candidates = [runtimeDirectory(variables)];
+  const fallbacks = process.platform === "win32" ? [envValue("SystemRoot", variables) ?? envValue("windir", variables) ?? "C:\\Windows"] : ["/tmp", "/var/tmp"];
+  for (const base of fallbacks) {
+    candidates.push(join6(base, process.platform === "win32" ? "Temp" : "", "gdharness"));
+  }
+  return [...new Set(candidates.map((path) => resolve4(path)))];
 }
 function processAlive(pid) {
   try {
@@ -26826,7 +27293,7 @@ function processAlive(pid) {
 function parseAnnouncement(file, pid) {
   let fields;
   try {
-    fields = asParams(JSON.parse(readFileSync3(file, "utf8")));
+    fields = asParams(JSON.parse(readFileSync6(file, "utf8")));
   } catch {
     return null;
   }
@@ -26844,17 +27311,28 @@ function parseAnnouncement(file, pid) {
     file
   };
 }
-function discoverRuntimes(directory = runtimeDirectory()) {
-  if (!existsSync3(directory)) {
+function discoverRuntimes(directories = runtimeDirectories()) {
+  const found = new Map;
+  for (const directory of directories) {
+    for (const endpoint of announcedIn(directory)) {
+      if (!found.has(endpoint.pid)) {
+        found.set(endpoint.pid, endpoint);
+      }
+    }
+  }
+  return [...found.values()].sort((a, b) => b.pid - a.pid);
+}
+function announcedIn(directory) {
+  if (!existsSync5(directory)) {
     return [];
   }
   const found = [];
-  for (const entry of readdirSync3(directory)) {
+  for (const entry of readdirSync4(directory)) {
     const match = ANNOUNCEMENT_PATTERN.exec(entry);
     if (!match) {
       continue;
     }
-    const file = join4(directory, entry);
+    const file = join6(directory, entry);
     const pid = Number.parseInt(match[1] ?? "", 10);
     const endpoint = processAlive(pid) ? parseAnnouncement(file, pid) : null;
     if (endpoint) {
@@ -26865,7 +27343,7 @@ function discoverRuntimes(directory = runtimeDirectory()) {
       } catch {}
     }
   }
-  return found.sort((a, b) => b.pid - a.pid);
+  return found;
 }
 function describe2(endpoint) {
   return `pid ${endpoint.pid} on ${endpoint.address}:${endpoint.port} (${endpoint.project.name || "unnamed"} at ${endpoint.project.path})`;
@@ -26987,19 +27465,6 @@ function runtimeRequest(endpoint, command, params, timeoutMs) {
   });
 }
 
-// src/server-version.ts
-import { readFileSync as readFileSync4 } from "node:fs";
-var DEBUG_MODE = process.env["DEBUG"] === "true";
-var GODOT_DEBUG_MODE_DEFAULT = process.env["GODOT_DEBUG"] === "true" || DEBUG_MODE;
-var SERVER_VERSION = (() => {
-  try {
-    const pkg = JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8"));
-    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-})();
-
 // src/tool-definitions.ts
 var PROJECT_PATH = {
   type: "string",
@@ -27904,6 +28369,8 @@ function buildToolDefinitions() {
 }
 
 // src/server.ts
+var UPDATE_NOTICE_EVERY = 500;
+var FEEDBACK_NOTICE_EVERY = 250;
 var run3 = promisify3(execFile3);
 var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
 var EDITOR_RESTART_TIMEOUT_MS = 90000;
@@ -27982,11 +28449,11 @@ function realPathOr(path) {
   }
 }
 function hasMainScene(projectFile) {
-  const scene = parseProjectGodot(readFileSync5(projectFile, "utf8"))["application"]?.["run/main_scene"];
+  const scene = parseProjectGodot(readFileSync7(projectFile, "utf8"))["application"]?.["run/main_scene"];
   return typeof scene === "string" && scene !== "";
 }
 function editorPlaysHeadless(projectFile) {
-  const runArgs = parseProjectGodot(readFileSync5(projectFile, "utf8"))["editor"]?.["run/main_run_args"];
+  const runArgs = parseProjectGodot(readFileSync7(projectFile, "utf8"))["editor"]?.["run/main_run_args"];
   return typeof runArgs === "string" && /(?:^|\s)--headless(?:\s|$)/.test(runArgs);
 }
 function camelCased(params) {
@@ -28002,10 +28469,14 @@ function camelCased(params) {
 class GodotServer {
   mcp;
   locator = new GodotLocator;
-  operationsScript = join5(__dirname2, "godot", "operations", "godot_operations.gd");
+  operationsScript = join7(__dirname2, "godot", "operations", "godot_operations.gd");
   godotBridge;
   tools = buildToolDefinitions();
   activeProcess = null;
+  updates = new UpdateCheck(SERVER_VERSION);
+  noticedUpdate = false;
+  callsSinceNotice = 0;
+  callsSinceFeedback = 0;
   lspClient = null;
   dapClient = null;
   bridgeStartupError = null;
@@ -28163,9 +28634,61 @@ class GodotServer {
       if (typeof args["projectPath"] === "string") {
         this.lastProjectPath = args["projectPath"];
       }
-      return await this.dispatch(spec.name, checked.op ?? "", args);
+      this.updates.refresh();
+      const answer = await this.answered(spec.name, checked.op ?? "", args);
+      return this.withFeedbackNotice(this.withUpdateNotice(answer));
     });
   }
+  async answered(tool, op, args) {
+    try {
+      return await this.dispatch(tool, op, args);
+    } catch (error) {
+      if (error instanceof McpError || error instanceof Refusal) {
+        throw error;
+      }
+      const where = op === "" ? tool : `${tool} op=${op}`;
+      console.error(`[SERVER] Unmodelled failure in ${where}:`, error);
+      return { content: [{ type: "text", text: defectReport2(where, error) }], isError: true };
+    }
+  }
+  withUpdateNotice(answer) {
+    this.callsSinceNotice += 1;
+    if (this.callsSinceNotice < UPDATE_NOTICE_EVERY && this.noticedUpdate) {
+      return answer;
+    }
+    const notice = this.updates.notice();
+    if (notice === null) {
+      return answer;
+    }
+    this.noticedUpdate = true;
+    this.callsSinceNotice = 0;
+    return {
+      ...answer,
+      content: [
+        ...answer.content,
+        {
+          type: "text",
+          text: JSON.stringify({
+            update_available: {
+              ...notice,
+              what_to_do: "Tell the user a newer gdharness is out, with what changed, and offer to take it. " + "Only run the upgrade command if they say yes: it restarts their editor and the " + "MCP server has to be reconnected afterwards."
+            }
+          }, null, 2)
+        }
+      ]
+    };
+  }
+  withFeedbackNotice(answer) {
+    this.callsSinceFeedback += 1;
+    if (this.callsSinceFeedback < FEEDBACK_NOTICE_EVERY) {
+      return answer;
+    }
+    this.callsSinceFeedback = 0;
+    return {
+      ...answer,
+      content: [...answer.content, { type: "text", text: feedbackNotice() }]
+    };
+  }
   validateArguments(spec, args) {
     const known = new Set([...Object.keys(spec.parameters), ...spec.operations ? ["op"] : []]);
     const unknown = Object.keys(args).filter((key) => !known.has(key));
@@ -28371,9 +28894,16 @@ class GodotServer {
         });
       }
       case "debug_control":
-        return await this.handleDAP(`dap_${op}`, args);
-      case "debug_state":
-        return await this.handleDAP(DEBUG_STATE_CALLS[op] ?? "dap_get_stack_trace", args);
+      case "debug_state": {
+        if (tool === "debug_state" && op === "output") {
+          return await this.handleDAP("dap_get_output", args);
+        }
+        const held = await this.debuggedGame();
+        if (!held.ok) {
+          return held.response;
+        }
+        return tool === "debug_control" ? await this.handleDAP(`dap_${op}`, args) : await this.handleDAP(DEBUG_STATE_CALLS[op] ?? "dap_get_stack_trace", args);
+      }
       default:
         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${tool}`);
     }
@@ -28393,8 +28923,8 @@ class GodotServer {
     if (path === undefined) {
       return { ok: false, response: this.createErrorResponse("projectPath is required.") };
     }
-    const file = join5(path, "project.godot");
-    if (!existsSync4(file)) {
+    const file = join7(path, "project.godot");
+    if (!existsSync6(file)) {
       return {
         ok: false,
         response: this.createErrorResponse(`Not a Godot project: ${path}`, [
@@ -28404,6 +28934,56 @@ class GodotServer {
     }
     return { ok: true, value: { path, file } };
   }
+  async debuggedGame() {
+    const game = this.activeProcess;
+    if (game === null) {
+      return {
+        ok: false,
+        response: this.createErrorResponse("No game is running, so there is no debug session to answer for.", ["Start one with editor_run start, which has the editor play it"])
+      };
+    }
+    if (!game.throughEditor) {
+      return {
+        ok: false,
+        response: this.createErrorResponse("The running game is its own process, so no debugger is holding it: breakpoints never hit and there is no stack to read.", [
+          "editor_run start plays it through the open editor, whose debugger the debug_* tools speak to",
+          "editor_status says whether an editor has reached this server"
+        ])
+      };
+    }
+    try {
+      await this.dap().attach();
+    } catch (error) {
+      return {
+        ok: false,
+        response: this.createErrorResponse(`The editor is playing the game but its debug adapter did not answer: ${errorMessage(error)}`, [
+          "Godot serves the debug adapter on 6006 unless --dap-port says otherwise",
+          "GDHARNESS_DAP_PORT points this server at another one"
+        ])
+      };
+    }
+    if (!this.dap().isStopped()) {
+      return {
+        ok: false,
+        response: this.createErrorResponse("The game is running, not stopped, so it has no stack and no scope to read.", [
+          "debug_breakpoint set puts a breakpoint on before the run, and it is waiting when the game starts",
+          "editor_output reads what the running game is printing"
+        ])
+      };
+    }
+    return { ok: true, value: game };
+  }
+  async refreshStaleClasses(projectPath) {
+    const stale = staleClassNames(projectPath);
+    if (stale.length === 0) {
+      return { ok: true, value: [] };
+    }
+    const refreshed = await this.operation("refresh_class_cache", {}, projectPath);
+    if (!refreshed.ok) {
+      return { ok: false, response: this.answer(refreshed) };
+    }
+    return { ok: true, value: stale };
+  }
   containProjectFiles(args) {
     const projectPath = readString(args, "projectPath");
     if (!projectPath) {
@@ -28489,7 +29069,7 @@ class GodotServer {
     if (!engine.ok) {
       return engine.response;
     }
-    const application = parseProjectGodot(readFileSync5(project.value.file, "utf8"))["application"] ?? {};
+    const application = parseProjectGodot(readFileSync7(project.value.file, "utf8"))["application"] ?? {};
     const name = application["config/name"];
     const mainScene = application["run/main_scene"];
     const info = {
@@ -28578,7 +29158,7 @@ class GodotServer {
     log.finish();
     const problems = log.select({ severity: "warning", sinceLastCall: false, limit: 200 });
     const verdict = {
-      exported: exitCode === 0 && log.count("error") === 0 && existsSync4(output.absolutePath),
+      exported: exitCode === 0 && log.count("error") === 0 && existsSync6(output.absolutePath),
       preset,
       outputPath: output.relativePath,
       debug,
@@ -28608,7 +29188,7 @@ class GodotServer {
       return contained.response;
     }
     const runner = "addons/gdUnit4/bin/GdUnitCmdTool.gd";
-    if (!existsSync4(join5(project.value.path, runner))) {
+    if (!existsSync6(join7(project.value.path, runner))) {
       return this.createErrorResponse(`gdUnit4 is not installed in this project: no ${runner}.`, [
         "Install gdUnit4 under addons/gdUnit4, from https://github.com/godot-gdunit-labs/gdUnit4"
       ]);
@@ -28656,14 +29236,14 @@ class GodotServer {
         resolve(false);
       });
     });
-    const reportsDir = join5(project.value.path, ".godot", "gdharness-reports");
+    const reportsDir = join7(project.value.path, ".godot", "gdharness-reports");
     let report = null;
     let reportProblem = null;
     try {
-      const written = existsSync4(reportsDir) ? readdirSync4(reportsDir).filter((name) => name.startsWith("report_")).sort((a, b) => Number(a.slice("report_".length)) - Number(b.slice("report_".length))) : [];
+      const written = existsSync6(reportsDir) ? readdirSync5(reportsDir).filter((name) => name.startsWith("report_")).sort((a, b) => Number(a.slice("report_".length)) - Number(b.slice("report_".length))) : [];
       const newest = written.at(-1);
       if (newest !== undefined) {
-        report = parseJUnit(readFileSync5(join5(reportsDir, newest, "results.xml"), "utf8"));
+        report = parseJUnit(readFileSync7(join7(reportsDir, newest, "results.xml"), "utf8"));
       }
     } catch (error) {
       reportProblem = errorMessage(error);
@@ -28779,7 +29359,7 @@ class GodotServer {
       addonIsStale: status.connected ? stale : undefined,
       bridgeAvailable: this.bridgeStartupError === null,
       startupError: this.bridgeStartupError,
-      staleNote: stale ? `The editor is running the ${status.addonVersion === "" ? "addon from before versions were reported" : status.addonVersion} addon while this server ships ${SERVER_VERSION}. Restart it with editor_launch restart to pick the new one up.` : undefined,
+      staleNote: stale ? addonMismatch(status.addonVersion, SERVER_VERSION) : undefined,
       note: isPortConflict ? "Bridge port is already in use. Another gdharness instance may own the editor bridge, so this server cannot report that editor connection." : undefined,
       suggestion: isPortConflict ? "Stop duplicate gdharness/MCP server instances or re-run the command from the same server process that owns the bridge port." : undefined
     };
@@ -28857,6 +29437,7 @@ class GodotServer {
       addonVersion: now.addonVersion,
       serverVersion: SERVER_VERSION,
       addonIsStale: now.addonVersion !== SERVER_VERSION,
+      staleNote: addonMismatch(now.addonVersion, SERVER_VERSION),
       tookMs: Date.now() - began
     });
   }
@@ -28876,6 +29457,13 @@ class GodotServer {
     if (!project.ok) {
       return project.response;
     }
+    if (this.godotBridge.isConnected()) {
+      return this.createErrorResponse("An editor is already connected to this server, and a second one would take the language server and debug adapter ports from it.", [
+        "editor_status says which editor is answering, and for which project",
+        "editor_launch restart replaces the connected editor rather than joining it",
+        "Close the open editor first if the new project is the one you want"
+      ]);
+    }
     const engine = await this.engine();
     if (!engine.ok) {
       return engine.response;
@@ -28883,7 +29471,8 @@ class GodotServer {
     this.logDebug(`Launching Godot editor for project: ${project.value.path}`);
     const editor = spawn(engine.value, editorArguments(project.value.path), {
       stdio: "ignore",
-      detached: true
+      detached: true,
+      env: { ...process.env, GDHARNESS_RUNTIME_DIR: runtimeDirectory() }
     });
     const started = await new Promise((resolve) => {
       editor.once("spawn", () => {
@@ -28923,6 +29512,10 @@ class GodotServer {
     if (!engine.ok) {
       return engine.response;
     }
+    const refreshed = await this.refreshStaleClasses(project.value.path);
+    if (!refreshed.ok) {
+      return refreshed.response;
+    }
     const sceneArgument = sceneToRun?.ok ? sceneToRun.relativePath : null;
     if (op === "check") {
       return await this.checkBoot(engine.value, project.value.path, sceneArgument, args);
@@ -28936,7 +29529,7 @@ class GodotServer {
       variables: process.env
     });
     if (this.godotBridge.isConnected() && (!headless || editorPlaysHeadless(project.value.file))) {
-      return await this.playThroughEditor(sceneArgument);
+      return await this.playThroughEditor(sceneArgument, refreshed.value);
     }
     const cmdArgs = runArguments({
       projectPath: project.value.path,
@@ -28956,10 +29549,11 @@ class GodotServer {
       through: "gdharness",
       pid: started.process.pid ?? null,
       arguments: cmdArgs,
+      refreshedClasses: refreshed.value,
       message: "Use editor_output for what it prints and editor_run stop to end it."
     });
   }
-  async playThroughEditor(scene) {
+  async playThroughEditor(scene, refreshedClasses) {
     const log = new GameLog;
     try {
       await this.dap().connect();
@@ -28985,6 +29579,7 @@ class GodotServer {
       started: true,
       through: "editor",
       scene: scene === null ? "the main scene" : `res://${scene}`,
+      refreshedClasses,
       message: "The editor is playing it, so its debugger holds it: the debug_* tools can reach it, " + "editor_output reads its console through the debug adapter, and editor_run stop ends it."
     });
   }
@@ -29159,8 +29754,8 @@ class GodotServer {
       return this.createErrorResponse(choice.problem);
     }
     const expectsScreenshot = command === "capture_screenshot" || command === "capture_viewport";
-    const screenshotDir = expectsScreenshot ? mkdtempSync2(join5(tmpdir3(), "gdharness-runtime-screenshot-")) : null;
-    const screenshotPath = screenshotDir ? join5(screenshotDir, "capture.png") : null;
+    const screenshotDir = expectsScreenshot ? mkdtempSync2(join7(tmpdir4(), "gdharness-runtime-screenshot-")) : null;
+    const screenshotPath = screenshotDir ? join7(screenshotDir, "capture.png") : null;
     try {
       const reply = await runtimeRequest(choice.endpoint, command, screenshotPath ? { ...params, output_path: screenshotPath } : params, timeoutMs);
       if (!reply.ok) {
@@ -29181,7 +29776,7 @@ class GodotServer {
       return {
         content: [
           { type: "text", text: `Screenshot captured: ${dimensions}` },
-          { type: "image", data: readFileSync5(screenshotPath).toString("base64"), mimeType: "image/png" }
+          { type: "image", data: readFileSync7(screenshotPath).toString("base64"), mimeType: "image/png" }
         ]
       };
     } finally {
@@ -29246,7 +29841,6 @@ async function runGodotServer() {
 
 // src/server-entry.ts
 await runGodotServer().catch((error) => {
-  const errorMessage = error instanceof Error ? error.message : "Unknown error";
-  console.error("Failed to run server:", errorMessage);
+  console.error(defectReport("gdharness server startup", error));
   process.exit(1);
 });