gdharness 1.0.28 → 1.0.29

package/build/cli.js

@@ -16309,7 +16309,7 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "editor_run",
-      description: "The run: starting the project, stopping it, or booting it once to see whether it comes up clean. start keeps it running and collecting output until it quits or is stopped, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. A run that quits on its own is kept, so a scene that prints an answer and quits is start, then editor_output until running is false. What runs is a scene: a SceneTree script is not an entry point here, so put the script on the root of a scene of its own and name that in scene. args hands the game its own flags, the ones it reads with OS.get_cmdline_user_args(), and a run carrying any is started by this server rather than by the editor. check boots it headless for a few frames, waits for it to quit, and answers with the verdict: whether it came up, and every error and warning it printed on the way. A start waits for the game to become something the runtime_* tools can talk to and says which it is under runtime: listening with the port it took, or why not, so the first call after a start does not have to be made twice. When it is not listening, mayYetAnnounce says whether that is final: false is a runtime that is not coming, true is a game still on its way up, which editor_status will see and runtimeWaitMs waits longer for. A start this server made also answers with transcript, the file both the run's streams are written to, so a watch on it can be armed off the start rather than off a second call.",
+      description: "The run: starting the project, stopping it, or booting it once to see whether it comes up clean. start keeps it running and collecting output until it quits or is stopped, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. A run that quits on its own is kept, so a scene that prints an answer and quits is start, then editor_output until running is false. What runs is a scene: a SceneTree script is not an entry point here, so put the script on the root of a scene of its own and name that in scene. args hands the game its own flags, the ones it reads with OS.get_cmdline_user_args(), and a run carrying any is started by this server rather than by the editor. check boots it headless for a few frames, waits for it to quit, and answers with the verdict: whether it came up, and every error and warning it printed on the way. start and check both wait first for a scan the open editor is running and for the class cache it writes just after, since a game booted in between resolves no global class, as does every other engine this server starts on the project; waitedForEditorScanMs says how long, and scanNote says when a scan ran past thirty seconds and the game started during it. A start waits for the game to become something the runtime_* tools can talk to and says which it is under runtime: listening with the port it took, or why not, so the first call after a start does not have to be made twice. When it is not listening, mayYetAnnounce says whether that is final: false is a runtime that is not coming, true is a game still on its way up, which editor_status will see and runtimeWaitMs waits longer for. A start this server made also answers with transcript, the file both the run's streams are written to, so a watch on it can be armed off the start rather than off a second call.",
       parameters: {
         projectPath: { ...PROJECT_PATH, ops: ["start", "check"] },
         scene: {
@@ -16426,7 +16426,7 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "editor_status",
-      description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable: runtimeConnected counts the games of the project this server serves, and runtimes lists every game on the machine with ofThisProject saying which is which, since a game of another project is reached only by naming its projectPath. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved and, when it was the server this one replaced, which pid kept it. A server replacing another of its project that holds the configured port waits for it to stand down and takes the port over, which takes a few seconds; bridgeHandover says so while it waits, and it moves only if that server has not let go within the wait.",
+      description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable: runtimeConnected counts the games of the project this server serves, and runtimes lists every game on the machine with ofThisProject saying which is which, since a game of another project is reached only by naming its projectPath. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. editor.scan says whether the editor is scanning or importing and how many milliseconds ago its last scan finished (finishedMsAgo), or is null when it did not answer: the editor rewrites the class cache just after a scan, and editor_run waits that out before starting a game, saying so under waitedForEditorScanMs. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved and, when it was the server this one replaced, which pid kept it. A server replacing another of its project that holds the configured port waits for it to stand down and takes the port over, which takes a few seconds; bridgeHandover says so while it waits, and it moves only if that server has not let go within the wait.",
       parameters: {},
       requires: []
     },
@@ -38557,6 +38557,33 @@ function outsideTheirRanges(spec, args) {
   }
   return complaints;
 }
+function scanWaitIn(payload) {
+  const waited = readNumber(payload, "waitedForEditorScanMs");
+  const note = readString(payload, "scanNote");
+  return {
+    ...waited === undefined ? {} : { waitedForEditorScanMs: waited },
+    ...note === undefined ? {} : { scanNote: note }
+  };
+}
+function withScanWait(outcome, scanned) {
+  if (scanned.waitedMs === 0) {
+    return outcome;
+  }
+  const said = scanWaitAnswer(scanned);
+  if (outcome.ok) {
+    return { ...outcome, payload: { ...outcome.payload, ...said } };
+  }
+  return said.scanNote === undefined ? outcome : { ...outcome, message: `${outcome.message} ${said.scanNote}` };
+}
+function scanWaitAnswer(scanned) {
+  if (scanned.waitedMs === 0) {
+    return {};
+  }
+  return {
+    waitedForEditorScanMs: scanned.waitedMs,
+    scanNote: scanned.stillScanning ? `The editor was still scanning the project after ${SCAN_WAIT_MS / 1000} seconds, so this ` + "game started during the scan and may have read a class cache being rewritten. If " + 'editor_output shows "Could not find type" for a class that is declared, editor_rescan ' + "waits for the scan to finish, and a start after it reads the finished cache." : undefined
+  };
+}
 function escapingPropertyValue(properties) {
   if (typeof properties !== "object" || properties === null) {
     return;
@@ -39491,6 +39518,47 @@ class GodotServer {
     }
     return { ok: true, value: stale };
   }
+  async untilTheEditorsScanIsWritten(projectPath) {
+    const open = this.godotBridge.getStatus().projectPath;
+    if (!this.godotBridge.isConnected() || open === undefined || !isSameDirectory(open, projectPath)) {
+      return { waitedMs: 0, stillScanning: false };
+    }
+    const started = Date.now();
+    let sawAScan = false;
+    let scanEndedAt = null;
+    for (;; ) {
+      const asked = Date.now();
+      let status;
+      try {
+        status = asParams(await this.godotBridge.invokeTool("scan_status", {}));
+      } catch {
+        return { waitedMs: Date.now() - started, stillScanning: false };
+      }
+      if (status["scanning"] === true || status["importing"] === true || status["pending"] === true) {
+        sawAScan = true;
+        if (Date.now() - started >= SCAN_WAIT_MS) {
+          return { waitedMs: Date.now() - started, stillScanning: true };
+        }
+        await new Promise((settle) => setTimeout(settle, 100));
+        continue;
+      }
+      const since = readNumber(status, "sinceScanFinishedMs");
+      scanEndedAt = since !== undefined && since >= 0 ? asked - since : sawAScan ? asked : null;
+      break;
+    }
+    let waitedForTheWrite = false;
+    if (scanEndedAt !== null) {
+      const writeDue = scanEndedAt + CACHE_WRITE_MS;
+      while (Date.now() < writeDue && (cacheWrittenAt(projectPath) ?? 0) < scanEndedAt) {
+        waitedForTheWrite = true;
+        await new Promise((settle) => setTimeout(settle, 50));
+      }
+    }
+    return {
+      waitedMs: sawAScan || waitedForTheWrite ? Date.now() - started : 0,
+      stillScanning: false
+    };
+  }
   containProjectFiles(args) {
     const projectPath = readString(args, "projectPath");
     if (!projectPath) {
@@ -39551,14 +39619,15 @@ class GodotServer {
       return engine.response;
     }
     const projectPath = project.value.path;
+    const scanned = await this.untilTheEditorsScanIsWritten(projectPath);
     const before = scriptsWithoutUid(projectPath);
     const imported = await runImport(engine.value, projectPath);
     if (!imported.ok) {
-      return this.answer(imported);
+      return this.answer(withScanWait(imported, scanned));
     }
     const after = scriptsWithoutUid(projectPath);
     const given = before.filter((script) => !after.includes(script));
-    return this.answer({
+    return this.answer(withScanWait({
       ok: true,
       messages: imported.messages,
       payload: {
@@ -39566,7 +39635,7 @@ class GodotServer {
         stillWithoutUid: after,
         note: uidsLeftNote(after.length)
       }
-    });
+    }, scanned));
   }
   async operation(operation, params, projectPath) {
     const engine = await this.engine();
@@ -39577,8 +39646,10 @@ class GodotServer {
         messages: []
       };
     }
+    const scanned = await this.untilTheEditorsScanIsWritten(projectPath);
     this.logDebug(`Running ${operation} in ${projectPath}: ${JSON.stringify(params)}`);
-    return await runOperation2({ godotPath: engine.value, script: this.operationsScript, debug: GODOT_DEBUG_MODE_DEFAULT }, operation, params, projectPath);
+    const outcome = await runOperation2({ godotPath: engine.value, script: this.operationsScript, debug: GODOT_DEBUG_MODE_DEFAULT }, operation, params, projectPath);
+    return withScanWait(outcome, scanned);
   }
   answer(outcome) {
     if (!outcome.ok) {
@@ -39760,6 +39831,7 @@ class GodotServer {
     if (!classes.ok) {
       return this.answer(classes);
     }
+    const scanned = scanWaitIn(classes.payload);
     const ours = `gdharness-reports/${randomUUID2()}`;
     const reports = `res://.godot/${ours}`;
     const ignored = readStringArray(args, "ignore") ?? [];
@@ -39850,7 +39922,8 @@ class GodotServer {
               hung,
               arguments: cmdArgs,
               entries: forAnswer(printed.slice(0, 60)),
-              savesNote
+              savesNote,
+              ...scanned
             }, null, 2)
           }
         ],
@@ -39885,6 +39958,7 @@ class GodotServer {
       orphans: orphans.total > 0 ? orphans.total : undefined,
       notRun: notRun > 0 ? notRun : undefined,
       savesNote,
+      ...scanned,
       note: verdict.startsWith("warnings") && warnings.length === 0 ? "gdUnit4 exits 101 for orphan nodes when nothing failed, and this run printed no count of them: orphan reporting may be off in the project settings." : notRun > 0 ? `This run stopped at the first failure in each suite it failed in, so ${notRun} case${notRun === 1 ? "" : "s"} never ran and count as neither passed nor failed. Leave failFast out to run every case.` : undefined,
       suites: unclean.map((suite) => ({
         name: suite.name,
@@ -40183,6 +40257,28 @@ class GodotServer {
       return null;
     }
   }
+  async editorScanState() {
+    if (!this.godotBridge.getStatus().connected) {
+      return null;
+    }
+    try {
+      const answer = await Promise.race([
+        this.godotBridge.invokeTool("scan_status", {}),
+        delay3(PLAYING_STATUS_MS).then(() => null)
+      ]);
+      if (answer === null) {
+        return null;
+      }
+      const since = readNumber(asParams(answer), "sinceScanFinishedMs");
+      return {
+        scanning: readBoolean(asParams(answer), "scanning") ?? false,
+        importing: readBoolean(asParams(answer), "importing") ?? false,
+        finishedMsAgo: since === undefined || since < 0 ? null : since
+      };
+    } catch {
+      return null;
+    }
+  }
   async handleEditorStatus() {
     const located = await this.locator.find();
     const announced = runtimesAnnounced();
@@ -40213,11 +40309,16 @@ class GodotServer {
         hold: current === null ? {} : await this.holdOf(current, active)
       };
     })();
-    const [games, { playing, active, hold }] = await Promise.all([pinged, asked]);
+    const [games, { playing, active, hold }, scan] = await Promise.all([
+      pinged,
+      asked,
+      this.editorScanState()
+    ]);
     return this.jsonTextResponse({
       editor: {
         ...this.getEditorStatusPayload(),
-        debugPort: playing?.debugPort ?? this.godotBridge.getStatus().debugPort
+        debugPort: playing?.debugPort ?? this.godotBridge.getStatus().debugPort,
+        scan
       },
       godot: {
         path: located.ok ? located.path : null,
@@ -40438,13 +40539,14 @@ class GodotServer {
     if (!engine.ok) {
       return engine.response;
     }
+    const scanned = await this.untilTheEditorsScanIsWritten(project.value.path);
     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, given.value, asked.value);
+      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value, scanned, asked.value);
     }
     await this.pickUpWhatTheEditorIsPlaying();
     let ended = null;
@@ -40463,7 +40565,7 @@ class GodotServer {
     const runtimeWaitMs = this.announceBudget(args, project.value.path);
     const editorWouldPlay = !headless || editorPlaysHeadless(project.value.file);
     if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0 && !needsItsOwnProcess(asked.value)) {
-      return await this.playThroughEditor(sceneArgument, refreshed.value, project.value.path, alreadyPlaying, runtimeWaitMs, ended);
+      return await this.playThroughEditor(sceneArgument, refreshed.value, scanned, project.value.path, alreadyPlaying, runtimeWaitMs, ended);
     }
     const cmdArgs = runArguments({
       projectPath: project.value.path,
@@ -40488,6 +40590,7 @@ class GodotServer {
       arguments: cmdArgs,
       transcript: started.transcript,
       refreshedClasses: refreshed.value,
+      ...scanWaitAnswer(scanned),
       savesNote: asked.value.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
       endedPreviousRun: endedPreviousRun(ended),
       runtime: await this.runtimeUp(project.value.path, alreadyPlaying, runtimeWaitMs, given.value.length > 0),
@@ -40569,7 +40672,7 @@ class GodotServer {
       writeBootNote(run.projectPath, took);
     }
   }
-  async playThroughEditor(scene, refreshedClasses, projectPath, alreadyPlaying, runtimeWaitMs, ended) {
+  async playThroughEditor(scene, refreshedClasses, scanned, projectPath, alreadyPlaying, runtimeWaitMs, ended) {
     const log = new GameLog;
     try {
       await this.dap().connect();
@@ -40620,6 +40723,7 @@ class GodotServer {
       through: "editor",
       scene: scene === null ? "the main scene" : `res://${scene}`,
       refreshedClasses,
+      ...scanWaitAnswer(scanned),
       debugPort: readNumber(playAnswer, "debugPort"),
       endedPreviousRun: endedPreviousRun(ended),
       breakpoints: breakpoints.applied.length === 0 ? undefined : this.breakpointsAsProjectSpells(projectPath, breakpoints.applied),
@@ -41123,7 +41227,7 @@ class GodotServer {
   currentRun() {
     return this.activeProcess ?? this.adoptRecordedRun();
   }
-  async checkBoot(godotPath, projectPath, scene, args, userArgs, asked = {}) {
+  async checkBoot(godotPath, projectPath, scene, args, userArgs, scanned, asked = {}) {
     const frames = readPositiveNumber(args, "frames") ?? 3;
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 60000;
     const cmdArgs = runArguments({ projectPath, headless: true, scene, quitAfter: frames, userArgs });
@@ -41153,6 +41257,7 @@ class GodotServer {
       frames,
       errors,
       warnings,
+      ...scanWaitAnswer(scanned),
       savesNote: asked.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
       entries: forAnswer(boot.log.select({ severity: "warning", sinceLastCall: false, limit: 200 }).entries)
     });
@@ -41536,6 +41641,10 @@ class GodotServer {
     return now === null ? [] : lost.filter((name) => now.has(name));
   }
   async rebuildClassCache(projectPath) {
+    const scanned = await this.untilTheEditorsScanIsWritten(projectPath);
+    return withScanWait(await this.rebuildClassCacheFromDisk(projectPath), scanned);
+  }
+  async rebuildClassCacheFromDisk(projectPath) {
     const before = cachedClasses(projectPath);
     const writtenBefore = cacheWrittenAt(projectPath);
     const noted = readClassNote(projectPath);
@@ -41924,7 +42033,7 @@ async function runGodotServer() {
   const server = new GodotServer;
   await server.run();
 }
-var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run7, __dirname2, EDITOR_RESTART_TIMEOUT_MS = 90000, HOLD_PING_MS = 2000, SLOWEST_FRAME_RATE = 20, PLAY_STARTS_WITHIN_MS = 30000, STOP_WAIT_MS = 1e4, EXIT_REPORTED_WITHIN_MS = 2000, CONSOLE_WRAPPER, LONGEST_BOOT_NOTED_MS, MOST_GROUPS = 20, VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, HANDOVER_MS, HANDOVER_POLL_MS = 250, CACHE_WRITE_MS = 2000, PLAYING_STATUS_MS = 1000, SCAN_START_MS = 2000, WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/";
+var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run7, __dirname2, EDITOR_RESTART_TIMEOUT_MS = 90000, HOLD_PING_MS = 2000, SLOWEST_FRAME_RATE = 20, PLAY_STARTS_WITHIN_MS = 30000, STOP_WAIT_MS = 1e4, EXIT_REPORTED_WITHIN_MS = 2000, CONSOLE_WRAPPER, LONGEST_BOOT_NOTED_MS, MOST_GROUPS = 20, VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, HANDOVER_MS, HANDOVER_POLL_MS = 250, CACHE_WRITE_MS = 2000, SCAN_WAIT_MS = 30000, PLAYING_STATUS_MS = 1000, SCAN_START_MS = 2000, WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/";
 var init_server3 = __esm(() => {
   init_mcp();
   init_stdio2();
@@ -43697,6 +43806,13 @@ a class it cannot resolve would go out of that file with it. The answer names th
 \`cacheRestored\`, so no fresh engine, CI run or clone inherits the short file. That is the same
 class \`unseenByEditor\` names, and the loss is not a reason to refuse the scan.
 
+The editor also scans on its own, when files change under it, and it rewrites that file just after
+the scan ends. Every engine this server starts on the project (a run, a boot check, a test run, a
+headless operation) waits until a scan in progress and the write after it are done, and says how
+long under \`waitedForEditorScanMs\`. A \`scanNote\` means a scan was still going after thirty
+seconds and the engine started anyway: a "Could not find type" from that engine is the scan, not
+the script, and \`editor_rescan\` followed by the same call again is the cure.
+
 A diagnostic about a member rather than a type, \`Static function "x()" not found in base "Y"\`
 about something the engine compiles, is a different thing and is no longer stale here: each ask
 gives the document back when its answer arrives, so the next one is read off disk. If one turns

package/build/godot/addons/gdharness_editor/tool_executor.gd

@@ -79,6 +79,7 @@ func _init_tools() -> void:
 		"disconnect_signal": [_scene_tools, "disconnect_signal"],
 		"list_connections": [_scene_tools, "list_connections"],
 		"rescan_filesystem": [_scene_tools, "rescan_filesystem"],
+		"scan_status": [_scene_tools, "scan_status"],
 		"global_classes": [_class_tools, "global_classes"],
 		"reload_script": [_class_tools, "reload_script"],
 		# Settings, for a caller that asked the editor rather than the file on disk

package/build/godot/addons/gdharness_editor/tools/scene_tools.gd

@@ -18,6 +18,12 @@ var _scans_finished: int = 0
 var _scans_finished_at_request: int = 0
 var _scan_pending: bool = false
 
+## When the last scan finished, on the engine's clock, or -1 before the first. The editor writes
+## the class cache a frame after it stops reporting a scan, measured on 4.7.2, so a game started
+## in between reads a file being rewritten; how long ago the scan ended is what tells a caller
+## whether that write can still be coming.
+var _scan_finished_at_msec: int = -1
+
 
 func set_editor_plugin(plugin: EditorPlugin) -> void:
 	_editor_plugin = plugin
@@ -31,6 +37,7 @@ func set_editor_plugin(plugin: EditorPlugin) -> void:
 func _scan_finished() -> void:
 	_scans_finished += 1
 	_scan_pending = false
+	_scan_finished_at_msec = Time.get_ticks_msec()
 
 
 func _refresh_and_reload(scene_path: String) -> void:
@@ -675,3 +682,22 @@ func rescan_filesystem(args: Dictionary) -> Dictionary:
 		"pending": _scan_pending,
 		"scansFinished": _scans_finished,
 	}
+
+
+## Whether the editor is scanning, and how long ago its last scan finished, without asking for one.
+##
+## For a caller about to start a game: the editor rewrites the class cache a frame after a scan
+## stops reporting, so a game booted during the scan or in that frame reads a file being rewritten.
+## Apart from `rescan_filesystem` because asking must not start or count anything.
+func scan_status(_args: Dictionary) -> Dictionary:
+	if not _editor_plugin:
+		return {"ok": false, "error": "Editor plugin unavailable"}
+	var filesystem: EditorFileSystem = EditorInterface.get_resource_filesystem()
+	return {
+		"ok": true,
+		"scanning": filesystem.is_scanning(),
+		"importing": filesystem.is_importing(),
+		"pending": _scan_pending,
+		"sinceScanFinishedMs":
+		-1 if _scan_finished_at_msec < 0 else Time.get_ticks_msec() - _scan_finished_at_msec,
+	}

package/build/index.js

@@ -30316,7 +30316,7 @@ var TOOL_SPECS = [
   },
   {
     name: "editor_run",
-    description: "The run: starting the project, stopping it, or booting it once to see whether it comes up clean. start keeps it running and collecting output until it quits or is stopped, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. A run that quits on its own is kept, so a scene that prints an answer and quits is start, then editor_output until running is false. What runs is a scene: a SceneTree script is not an entry point here, so put the script on the root of a scene of its own and name that in scene. args hands the game its own flags, the ones it reads with OS.get_cmdline_user_args(), and a run carrying any is started by this server rather than by the editor. check boots it headless for a few frames, waits for it to quit, and answers with the verdict: whether it came up, and every error and warning it printed on the way. A start waits for the game to become something the runtime_* tools can talk to and says which it is under runtime: listening with the port it took, or why not, so the first call after a start does not have to be made twice. When it is not listening, mayYetAnnounce says whether that is final: false is a runtime that is not coming, true is a game still on its way up, which editor_status will see and runtimeWaitMs waits longer for. A start this server made also answers with transcript, the file both the run's streams are written to, so a watch on it can be armed off the start rather than off a second call.",
+    description: "The run: starting the project, stopping it, or booting it once to see whether it comes up clean. start keeps it running and collecting output until it quits or is stopped, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. A run that quits on its own is kept, so a scene that prints an answer and quits is start, then editor_output until running is false. What runs is a scene: a SceneTree script is not an entry point here, so put the script on the root of a scene of its own and name that in scene. args hands the game its own flags, the ones it reads with OS.get_cmdline_user_args(), and a run carrying any is started by this server rather than by the editor. check boots it headless for a few frames, waits for it to quit, and answers with the verdict: whether it came up, and every error and warning it printed on the way. start and check both wait first for a scan the open editor is running and for the class cache it writes just after, since a game booted in between resolves no global class, as does every other engine this server starts on the project; waitedForEditorScanMs says how long, and scanNote says when a scan ran past thirty seconds and the game started during it. A start waits for the game to become something the runtime_* tools can talk to and says which it is under runtime: listening with the port it took, or why not, so the first call after a start does not have to be made twice. When it is not listening, mayYetAnnounce says whether that is final: false is a runtime that is not coming, true is a game still on its way up, which editor_status will see and runtimeWaitMs waits longer for. A start this server made also answers with transcript, the file both the run's streams are written to, so a watch on it can be armed off the start rather than off a second call.",
     parameters: {
       projectPath: { ...PROJECT_PATH, ops: ["start", "check"] },
       scene: {
@@ -30433,7 +30433,7 @@ var TOOL_SPECS = [
   },
   {
     name: "editor_status",
-    description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable: runtimeConnected counts the games of the project this server serves, and runtimes lists every game on the machine with ofThisProject saying which is which, since a game of another project is reached only by naming its projectPath. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved and, when it was the server this one replaced, which pid kept it. A server replacing another of its project that holds the configured port waits for it to stand down and takes the port over, which takes a few seconds; bridgeHandover says so while it waits, and it moves only if that server has not let go within the wait.",
+    description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable: runtimeConnected counts the games of the project this server serves, and runtimes lists every game on the machine with ofThisProject saying which is which, since a game of another project is reached only by naming its projectPath. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. editor.scan says whether the editor is scanning or importing and how many milliseconds ago its last scan finished (finishedMsAgo), or is null when it did not answer: the editor rewrites the class cache just after a scan, and editor_run waits that out before starting a game, saying so under waitedForEditorScanMs. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved and, when it was the server this one replaced, which pid kept it. A server replacing another of its project that holds the configured port waits for it to stand down and takes the port over, which takes a few seconds; bridgeHandover says so while it waits, and it moves only if that server has not let go within the wait.",
     parameters: {},
     requires: []
   },
@@ -31263,6 +31263,34 @@ var SUCCESSOR_CHECK_MS = 1e4;
 var HANDOVER_MS = SUCCESSOR_CHECK_MS + 5000;
 var HANDOVER_POLL_MS = 250;
 var CACHE_WRITE_MS = 2000;
+var SCAN_WAIT_MS = 30000;
+function scanWaitIn(payload) {
+  const waited = readNumber(payload, "waitedForEditorScanMs");
+  const note = readString(payload, "scanNote");
+  return {
+    ...waited === undefined ? {} : { waitedForEditorScanMs: waited },
+    ...note === undefined ? {} : { scanNote: note }
+  };
+}
+function withScanWait(outcome, scanned) {
+  if (scanned.waitedMs === 0) {
+    return outcome;
+  }
+  const said = scanWaitAnswer(scanned);
+  if (outcome.ok) {
+    return { ...outcome, payload: { ...outcome.payload, ...said } };
+  }
+  return said.scanNote === undefined ? outcome : { ...outcome, message: `${outcome.message} ${said.scanNote}` };
+}
+function scanWaitAnswer(scanned) {
+  if (scanned.waitedMs === 0) {
+    return {};
+  }
+  return {
+    waitedForEditorScanMs: scanned.waitedMs,
+    scanNote: scanned.stillScanning ? `The editor was still scanning the project after ${SCAN_WAIT_MS / 1000} seconds, so this ` + "game started during the scan and may have read a class cache being rewritten. If " + 'editor_output shows "Could not find type" for a class that is declared, editor_rescan ' + "waits for the scan to finish, and a start after it reads the finished cache." : undefined
+  };
+}
 var PLAYING_STATUS_MS = 1000;
 var SCAN_START_MS = 2000;
 var WAIT_FOR_RUN_MS = 600000;
@@ -32230,6 +32258,47 @@ class GodotServer {
     }
     return { ok: true, value: stale };
   }
+  async untilTheEditorsScanIsWritten(projectPath) {
+    const open = this.godotBridge.getStatus().projectPath;
+    if (!this.godotBridge.isConnected() || open === undefined || !isSameDirectory(open, projectPath)) {
+      return { waitedMs: 0, stillScanning: false };
+    }
+    const started = Date.now();
+    let sawAScan = false;
+    let scanEndedAt = null;
+    for (;; ) {
+      const asked = Date.now();
+      let status;
+      try {
+        status = asParams(await this.godotBridge.invokeTool("scan_status", {}));
+      } catch {
+        return { waitedMs: Date.now() - started, stillScanning: false };
+      }
+      if (status["scanning"] === true || status["importing"] === true || status["pending"] === true) {
+        sawAScan = true;
+        if (Date.now() - started >= SCAN_WAIT_MS) {
+          return { waitedMs: Date.now() - started, stillScanning: true };
+        }
+        await new Promise((settle) => setTimeout(settle, 100));
+        continue;
+      }
+      const since = readNumber(status, "sinceScanFinishedMs");
+      scanEndedAt = since !== undefined && since >= 0 ? asked - since : sawAScan ? asked : null;
+      break;
+    }
+    let waitedForTheWrite = false;
+    if (scanEndedAt !== null) {
+      const writeDue = scanEndedAt + CACHE_WRITE_MS;
+      while (Date.now() < writeDue && (cacheWrittenAt(projectPath) ?? 0) < scanEndedAt) {
+        waitedForTheWrite = true;
+        await new Promise((settle) => setTimeout(settle, 50));
+      }
+    }
+    return {
+      waitedMs: sawAScan || waitedForTheWrite ? Date.now() - started : 0,
+      stillScanning: false
+    };
+  }
   containProjectFiles(args) {
     const projectPath = readString(args, "projectPath");
     if (!projectPath) {
@@ -32290,14 +32359,15 @@ class GodotServer {
       return engine.response;
     }
     const projectPath = project.value.path;
+    const scanned = await this.untilTheEditorsScanIsWritten(projectPath);
     const before = scriptsWithoutUid(projectPath);
     const imported = await runImport(engine.value, projectPath);
     if (!imported.ok) {
-      return this.answer(imported);
+      return this.answer(withScanWait(imported, scanned));
     }
     const after = scriptsWithoutUid(projectPath);
     const given = before.filter((script) => !after.includes(script));
-    return this.answer({
+    return this.answer(withScanWait({
       ok: true,
       messages: imported.messages,
       payload: {
@@ -32305,7 +32375,7 @@ class GodotServer {
         stillWithoutUid: after,
         note: uidsLeftNote(after.length)
       }
-    });
+    }, scanned));
   }
   async operation(operation, params, projectPath) {
     const engine = await this.engine();
@@ -32316,8 +32386,10 @@ class GodotServer {
         messages: []
       };
     }
+    const scanned = await this.untilTheEditorsScanIsWritten(projectPath);
     this.logDebug(`Running ${operation} in ${projectPath}: ${JSON.stringify(params)}`);
-    return await runOperation({ godotPath: engine.value, script: this.operationsScript, debug: GODOT_DEBUG_MODE_DEFAULT }, operation, params, projectPath);
+    const outcome = await runOperation({ godotPath: engine.value, script: this.operationsScript, debug: GODOT_DEBUG_MODE_DEFAULT }, operation, params, projectPath);
+    return withScanWait(outcome, scanned);
   }
   answer(outcome) {
     if (!outcome.ok) {
@@ -32499,6 +32571,7 @@ class GodotServer {
     if (!classes.ok) {
       return this.answer(classes);
     }
+    const scanned = scanWaitIn(classes.payload);
     const ours = `gdharness-reports/${randomUUID2()}`;
     const reports = `res://.godot/${ours}`;
     const ignored = readStringArray(args, "ignore") ?? [];
@@ -32589,7 +32662,8 @@ class GodotServer {
               hung,
               arguments: cmdArgs,
               entries: forAnswer(printed.slice(0, 60)),
-              savesNote
+              savesNote,
+              ...scanned
             }, null, 2)
           }
         ],
@@ -32624,6 +32698,7 @@ class GodotServer {
       orphans: orphans.total > 0 ? orphans.total : undefined,
       notRun: notRun > 0 ? notRun : undefined,
       savesNote,
+      ...scanned,
       note: verdict.startsWith("warnings") && warnings.length === 0 ? "gdUnit4 exits 101 for orphan nodes when nothing failed, and this run printed no count of them: orphan reporting may be off in the project settings." : notRun > 0 ? `This run stopped at the first failure in each suite it failed in, so ${notRun} case${notRun === 1 ? "" : "s"} never ran and count as neither passed nor failed. Leave failFast out to run every case.` : undefined,
       suites: unclean.map((suite) => ({
         name: suite.name,
@@ -32922,6 +32997,28 @@ class GodotServer {
       return null;
     }
   }
+  async editorScanState() {
+    if (!this.godotBridge.getStatus().connected) {
+      return null;
+    }
+    try {
+      const answer = await Promise.race([
+        this.godotBridge.invokeTool("scan_status", {}),
+        delay3(PLAYING_STATUS_MS).then(() => null)
+      ]);
+      if (answer === null) {
+        return null;
+      }
+      const since = readNumber(asParams(answer), "sinceScanFinishedMs");
+      return {
+        scanning: readBoolean(asParams(answer), "scanning") ?? false,
+        importing: readBoolean(asParams(answer), "importing") ?? false,
+        finishedMsAgo: since === undefined || since < 0 ? null : since
+      };
+    } catch {
+      return null;
+    }
+  }
   async handleEditorStatus() {
     const located = await this.locator.find();
     const announced = runtimesAnnounced();
@@ -32952,11 +33049,16 @@ class GodotServer {
         hold: current === null ? {} : await this.holdOf(current, active)
       };
     })();
-    const [games, { playing, active, hold }] = await Promise.all([pinged, asked]);
+    const [games, { playing, active, hold }, scan] = await Promise.all([
+      pinged,
+      asked,
+      this.editorScanState()
+    ]);
     return this.jsonTextResponse({
       editor: {
         ...this.getEditorStatusPayload(),
-        debugPort: playing?.debugPort ?? this.godotBridge.getStatus().debugPort
+        debugPort: playing?.debugPort ?? this.godotBridge.getStatus().debugPort,
+        scan
       },
       godot: {
         path: located.ok ? located.path : null,
@@ -33177,13 +33279,14 @@ class GodotServer {
     if (!engine.ok) {
       return engine.response;
     }
+    const scanned = await this.untilTheEditorsScanIsWritten(project.value.path);
     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, given.value, asked.value);
+      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value, scanned, asked.value);
     }
     await this.pickUpWhatTheEditorIsPlaying();
     let ended = null;
@@ -33202,7 +33305,7 @@ class GodotServer {
     const runtimeWaitMs = this.announceBudget(args, project.value.path);
     const editorWouldPlay = !headless || editorPlaysHeadless(project.value.file);
     if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0 && !needsItsOwnProcess(asked.value)) {
-      return await this.playThroughEditor(sceneArgument, refreshed.value, project.value.path, alreadyPlaying, runtimeWaitMs, ended);
+      return await this.playThroughEditor(sceneArgument, refreshed.value, scanned, project.value.path, alreadyPlaying, runtimeWaitMs, ended);
     }
     const cmdArgs = runArguments({
       projectPath: project.value.path,
@@ -33227,6 +33330,7 @@ class GodotServer {
       arguments: cmdArgs,
       transcript: started.transcript,
       refreshedClasses: refreshed.value,
+      ...scanWaitAnswer(scanned),
       savesNote: asked.value.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
       endedPreviousRun: endedPreviousRun(ended),
       runtime: await this.runtimeUp(project.value.path, alreadyPlaying, runtimeWaitMs, given.value.length > 0),
@@ -33308,7 +33412,7 @@ class GodotServer {
       writeBootNote(run.projectPath, took);
     }
   }
-  async playThroughEditor(scene, refreshedClasses, projectPath, alreadyPlaying, runtimeWaitMs, ended) {
+  async playThroughEditor(scene, refreshedClasses, scanned, projectPath, alreadyPlaying, runtimeWaitMs, ended) {
     const log = new GameLog;
     try {
       await this.dap().connect();
@@ -33359,6 +33463,7 @@ class GodotServer {
       through: "editor",
       scene: scene === null ? "the main scene" : `res://${scene}`,
       refreshedClasses,
+      ...scanWaitAnswer(scanned),
       debugPort: readNumber(playAnswer, "debugPort"),
       endedPreviousRun: endedPreviousRun(ended),
       breakpoints: breakpoints.applied.length === 0 ? undefined : this.breakpointsAsProjectSpells(projectPath, breakpoints.applied),
@@ -33862,7 +33967,7 @@ class GodotServer {
   currentRun() {
     return this.activeProcess ?? this.adoptRecordedRun();
   }
-  async checkBoot(godotPath, projectPath, scene, args, userArgs, asked = {}) {
+  async checkBoot(godotPath, projectPath, scene, args, userArgs, scanned, asked = {}) {
     const frames = readPositiveNumber(args, "frames") ?? 3;
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 60000;
     const cmdArgs = runArguments({ projectPath, headless: true, scene, quitAfter: frames, userArgs });
@@ -33892,6 +33997,7 @@ class GodotServer {
       frames,
       errors,
       warnings,
+      ...scanWaitAnswer(scanned),
       savesNote: asked.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
       entries: forAnswer(boot.log.select({ severity: "warning", sinceLastCall: false, limit: 200 }).entries)
     });
@@ -34275,6 +34381,10 @@ class GodotServer {
     return now === null ? [] : lost.filter((name) => now.has(name));
   }
   async rebuildClassCache(projectPath) {
+    const scanned = await this.untilTheEditorsScanIsWritten(projectPath);
+    return withScanWait(await this.rebuildClassCacheFromDisk(projectPath), scanned);
+  }
+  async rebuildClassCacheFromDisk(projectPath) {
     const before = cachedClasses(projectPath);
     const writtenBefore = cacheWrittenAt(projectPath);
     const noted = readClassNote(projectPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "1.0.28",
+  "version": "1.0.29",
   "mcpName": "io.github.Aureliolo/gdharness",
   "description": "A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.",
   "type": "module",