fix(dev): classify dirty-tree watch invalidations

scripts/run-node.mjs

@@ -194,48 +194,62 @@ const hasSourceMtimeChanged = (stampMtime, deps) => {
   return latestSourceMtime != null && latestSourceMtime > stampMtime;
 };
 
-const shouldBuild = (deps) => {
+export const resolveBuildRequirement = (deps) => {
   if (deps.env.OPENCLAW_FORCE_BUILD === "1") {
-    return true;
+    return { shouldBuild: true, reason: "force_build" };
   }
   const stamp = readBuildStamp(deps);
   if (stamp.mtime == null) {
-    return true;
+    return { shouldBuild: true, reason: "missing_build_stamp" };
   }
   if (statMtime(deps.distEntry, deps.fs) == null) {
-    return true;
+    return { shouldBuild: true, reason: "missing_dist_entry" };
   }
 
   for (const filePath of deps.configFiles) {
     const mtime = statMtime(filePath, deps.fs);
     if (mtime != null && mtime > stamp.mtime) {
-      return true;
+      return { shouldBuild: true, reason: "config_newer" };
     }
   }
 
   const currentHead = resolveGitHead(deps);
   if (currentHead && !stamp.head) {
-    return true;
+    return { shouldBuild: true, reason: "build_stamp_missing_head" };
   }
   if (currentHead && stamp.head && currentHead !== stamp.head) {
-    return true;
+    return { shouldBuild: true, reason: "git_head_changed" };
   }
   if (currentHead) {
     const dirty = hasDirtySourceTree(deps);
     if (dirty === true) {
-      return true;
+      return { shouldBuild: true, reason: "dirty_watched_tree" };
     }
     if (dirty === false) {
-      return false;
+      return { shouldBuild: false, reason: "clean" };
     }
   }
 
   if (hasSourceMtimeChanged(stamp.mtime, deps)) {
-    return true;
+    return { shouldBuild: true, reason: "source_mtime_newer" };
   }
-  return false;
+  return { shouldBuild: false, reason: "clean" };
 };
 
+const BUILD_REASON_LABELS = {
+  force_build: "forced by OPENCLAW_FORCE_BUILD",
+  missing_build_stamp: "build stamp missing",
+  missing_dist_entry: "dist entry missing",
+  config_newer: "config newer than build stamp",
+  build_stamp_missing_head: "build stamp missing git head",
+  git_head_changed: "git head changed",
+  dirty_watched_tree: "dirty watched source tree",
+  source_mtime_newer: "source mtime newer than build stamp",
+  clean: "clean",
+};
+
+const formatBuildReason = (reason) => BUILD_REASON_LABELS[reason] ?? reason;
+
 const logRunner = (message, deps) => {
   if (deps.env.OPENCLAW_RUNNER_LOG === "0") {
     return;
@@ -307,14 +321,18 @@ export async function runNodeMain(params = {}) {
   }));
   deps.configFiles = runNodeConfigFiles.map((filePath) => path.join(deps.cwd, filePath));
 
-  if (!shouldBuild(deps)) {
+  const buildRequirement = resolveBuildRequirement(deps);
+  if (!buildRequirement.shouldBuild) {
     if (!syncRuntimeArtifacts(deps)) {
       return 1;
     }
     return await runOpenClaw(deps);
   }
 
-  logRunner("Building TypeScript (dist is stale).", deps);
+  logRunner(
+    `Building TypeScript (dist is stale: ${buildRequirement.reason} - ${formatBuildReason(buildRequirement.reason)}).`,
+    deps,
+  );
   const buildCmd = deps.execPath;
   const buildArgs = compilerArgs;
   const build = deps.spawn(buildCmd, buildArgs, {