fix: align tool exit codes with response success

Assets/Tests/Editor/CompileResponseFactoryTests.cs

@@ -77,12 +77,14 @@ public void CreateResponse_WhenForceCompileIsUnknown_ExplainsNullDetails()
             CompileResponse response =
                 CompileResponseFactory.CreateResponse(result, forceRecompile: true);
 
-            Assert.That(response.Success, Is.Null);
+            Assert.That(response.Success, Is.False);
             Assert.That(response.ErrorCount, Is.Null);
             Assert.That(response.WarningCount, Is.Null);
             Assert.That(response.Errors, Is.Null);
             Assert.That(response.Warnings, Is.Null);
             Assert.That(response.Message, Is.EqualTo(ForceCompileUnknownResult.MessageText));
+            Assert.That(response.ErrorCode, Is.EqualTo(ForceCompileUnknownResult.ErrorCodeText));
+            Assert.That(response.NextActions, Is.Not.Empty);
         }
 
         [Test]
@@ -102,12 +104,14 @@ public void CreateResponse_WhenForceCompileHasOutcome_ExplainsNullDetails()
             CompileResponse response =
                 CompileResponseFactory.CreateResponse(result, forceRecompile: true);
 
-            Assert.That(response.Success, Is.True);
+            Assert.That(response.Success, Is.False);
             Assert.That(response.ErrorCount, Is.Null);
             Assert.That(response.WarningCount, Is.Null);
             Assert.That(response.Errors, Is.Null);
             Assert.That(response.Warnings, Is.Null);
             Assert.That(response.Message, Is.EqualTo(ForceCompileUnknownResult.MessageText));
+            Assert.That(response.ErrorCode, Is.EqualTo(ForceCompileUnknownResult.ErrorCodeText));
+            Assert.That(response.NextActions, Is.Not.Empty);
         }
 
         [Test]
@@ -142,7 +146,7 @@ public void CreateResponse_WhenIndeterminateNonForceCompileHasCounts_PreservesCo
             CompileResponse response =
                 CompileResponseFactory.CreateResponse(result, forceRecompile: false);
 
-            Assert.That(response.Success, Is.Null);
+            Assert.That(response.Success, Is.False);
             Assert.That(response.ErrorCount, Is.EqualTo(1));
             Assert.That(response.WarningCount, Is.EqualTo(1));
             Assert.That(response.Errors, Is.Null);

Assets/Tests/Editor/CompileStatusBridgeCommandTests.cs

@@ -158,7 +158,7 @@ public void BuildResponse_WhenUnityIsIdleAndPendingRequestObservedReload_Returns
 
             Assert.That(response.Ready, Is.True);
             Assert.That(response.HasResult, Is.True);
-            Assert.That(response.Result["Success"]?.Type, Is.EqualTo(JTokenType.Null));
+            Assert.That(response.Result["Success"]?.Value<bool>(), Is.False);
             Assert.That(response.Result["ErrorCount"]?.Type, Is.EqualTo(JTokenType.Null));
             Assert.That(response.Result["Warnings"]?.Type, Is.EqualTo(JTokenType.Null));
             Assert.That(response.Result["Message"]?.ToString(), Does.Contain("reloaded scripts"));
@@ -216,11 +216,13 @@ public void BuildResponse_WhenForceCompilePendingRequestHasNoResult_ReturnsExpla
 
             Assert.That(response.Ready, Is.True);
             Assert.That(response.HasResult, Is.True);
-            Assert.That(response.Result["Success"]?.Type, Is.EqualTo(JTokenType.Null));
+            Assert.That(response.Result["Success"]?.Value<bool>(), Is.False);
             Assert.That(response.Result["ErrorCount"]?.Type, Is.EqualTo(JTokenType.Null));
             Assert.That(
                 response.Result["Message"]?.ToString(),
                 Is.EqualTo(ForceCompileUnknownResult.MessageText));
+            Assert.That(response.Result["ErrorCode"]?.ToString(), Is.EqualTo(ForceCompileUnknownResult.ErrorCodeText));
+            Assert.That(response.Result["NextActions"]?.Type, Is.EqualTo(JTokenType.Array));
         }
 
     }

Assets/Tests/Editor/JsonRpcRequestProcessorCliVersionGateTests.cs

@@ -923,7 +923,6 @@ public void InvalidateCache()
 
         private sealed class SingleFlightTestResponse : UnityCliLoopToolResponse
         {
-            public bool Success { get; set; } = true;
         }
     }
 }

Assets/Tests/Editor/JsonRpcResponseFactoryWireShapeCharacterizationTests.cs

@@ -143,7 +143,6 @@ private static string BuildToolRequest(string toolName, int id)
 
         private sealed class DeterministicSuccessResponse : UnityCliLoopToolResponse
         {
-            public bool Success { get; set; } = true;
         }
 
         private sealed class DeterministicSuccessTool : IUnityCliLoopTool

Assets/Tests/Editor/ToolExecutionSessionTests.cs

@@ -256,7 +256,6 @@ public void InvalidateCache()
 
         private sealed class SessionTestResponse : UnityCliLoopToolResponse
         {
-            public bool Success { get; set; } = true;
         }
     }
 }

Packages/src/Editor/FirstPartyTools/ClearConsole/ClearConsoleResponse.cs

@@ -10,11 +10,6 @@ namespace io.github.hatayama.UnityCliLoop.FirstPartyTools
     /// </summary>
     public class ClearConsoleResponse : UnityCliLoopToolResponse
     {
-        /// <summary>
-        /// Whether the console clear operation was successful
-        /// </summary>
-        public bool Success { get; set; }
-
         /// <summary>
         /// Number of logs that were cleared from the console
         /// </summary>
@@ -101,4 +96,4 @@ public ClearedLogCounts(int errorCount, int warningCount, int logCount)
             LogCount = logCount;
         }
     }
-} 
+}

Packages/src/Editor/FirstPartyTools/Compile/CompileResponse.cs

@@ -27,13 +27,6 @@ public CompileIssue() { }
     /// </summary>
     public class CompileResponse : UnityCliLoopToolResponse
     {
-        /// <summary>
-        /// Whether compilation was successful.
-        /// Null is used when the tool cannot reliably determine the result yet (e.g., forced recompile/domain reload),
-        /// to avoid misleading clients into treating "0 errors" as a confirmed success.
-        /// </summary>
-        public bool? Success { get; set; }
-
         /// <summary>
         /// Number of compilation errors.
         /// Null is used when the tool intentionally does not provide details (e.g., forced recompile),
@@ -67,6 +60,8 @@ public class CompileResponse : UnityCliLoopToolResponse
         /// </summary>
         public string Message { get; set; }
 
+        public string ErrorCode { get; set; }
+
         /// <summary>
         /// Optional recovery steps when compile cannot proceed automatically.
         /// </summary>
@@ -82,7 +77,7 @@ public class CompileResponse : UnityCliLoopToolResponse
         /// Create a new CompileResponse
         /// </summary>
         public CompileResponse(
-            bool? success,
+            bool success,
             int? errorCount,
             int? warningCount,
             CompileIssue[] errors,

Packages/src/Editor/FirstPartyTools/Compile/CompileResponseFactory.cs

@@ -39,7 +39,7 @@ internal static CompileResponse CreateResponse(
             if (result.IsIndeterminate)
             {
                 return new CompileResponse(
-                    success: result.Success,
+                    success: result.Success == true,
                     errorCount: result.ErrorCount,
                     warningCount: result.WarningCount,
                     errors: null,
@@ -48,7 +48,7 @@ internal static CompileResponse CreateResponse(
             }
 
             CompileResponse response = new CompileResponse(
-                success: result.Success,
+                success: result.Success == true,
                 errorCount: result.Errors?.Length ?? 0,
                 warningCount: result.Warnings?.Length ?? 0,
                 errors: ToIssues(result.Errors),
@@ -75,14 +75,17 @@ private static string[] CreateExternalSceneChangeNextActions(string message)
 
         private static CompileResponse CreateForceCompileResult(CompileResult result)
         {
-            ForceCompileUnknownResult unknownResult = ForceCompileUnknownResult.Create(result.Success);
-            return new CompileResponse(
+            ForceCompileUnknownResult unknownResult = ForceCompileUnknownResult.Create();
+            CompileResponse response = new CompileResponse(
                 success: unknownResult.Success,
                 errorCount: unknownResult.ErrorCount,
                 warningCount: unknownResult.WarningCount,
                 errors: null,
                 warnings: null,
                 message: unknownResult.Message);
+            response.ErrorCode = ForceCompileUnknownResult.ErrorCodeText;
+            response.NextActions = new[] { ForceCompileUnknownResult.NextActionText };
+            return response;
         }
 
         private static CompileIssue[] ToIssues(UnityEditor.Compilation.CompilerMessage[] messages)

Packages/src/Editor/FirstPartyTools/ExecuteDynamicCode/ExecuteDynamicCodeResponse.cs

@@ -12,9 +12,6 @@ namespace io.github.hatayama.UnityCliLoop.FirstPartyTools
     /// </summary>
     public class ExecuteDynamicCodeResponse : UnityCliLoopToolResponse, IUnityCliLoopTimingResponse
     {
-        /// <summary>Execution success flag</summary>
-        public bool Success { get; set; }
-
         /// <summary>Execution result</summary>
         public string Result { get; set; }
 

Packages/src/Editor/FirstPartyTools/PausePoint/PausePointTools.cs

@@ -46,9 +46,6 @@ public class ClearPausePointSchema : UnityCliLoopToolSchema
     /// </summary>
     public class PausePointResponse : UnityCliLoopToolResponse
     {
-        // Defaults to true so existing snapshot/clear paths keep their prior semantics.
-        // Only explicit validation failures set this to false.
-        public bool Success { get; set; } = true;
         public string Id { get; set; } = string.Empty;
         public int ResolvedLine { get; set; }
         public string ResolvedMethod { get; set; } = string.Empty;

Packages/src/Editor/FirstPartyTools/Raycast/RaycastResponse.cs

@@ -9,7 +9,6 @@ namespace io.github.hatayama.UnityCliLoop.FirstPartyTools
     /// </summary>
     public class RaycastResponse : UnityCliLoopToolResponse
     {
-        public bool Success { get; set; }
         public string Message { get; set; } = "";
         public bool Hit { get; set; }
         public string? HitGameObjectName { get; set; }

Packages/src/Editor/FirstPartyTools/RecordInput/RecordInputResponse.cs

@@ -9,7 +9,6 @@ namespace io.github.hatayama.UnityCliLoop.FirstPartyTools
     /// </summary>
     public class RecordInputResponse : UnityCliLoopToolResponse
     {
-        public bool Success { get; set; }
         public string Message { get; set; } = "";
         public string Action { get; set; } = "";
         public string? OutputPath { get; set; }

Packages/src/Editor/FirstPartyTools/ReplayInput/ReplayInputResponse.cs

@@ -9,7 +9,6 @@ namespace io.github.hatayama.UnityCliLoop.FirstPartyTools
     /// </summary>
     public class ReplayInputResponse : UnityCliLoopToolResponse
     {
-        public bool Success { get; set; }
         public string Message { get; set; } = "";
         public string Action { get; set; } = "";
         public string? InputPath { get; set; }

Packages/src/Editor/FirstPartyTools/RunTests/RunTestsResponse.cs

@@ -19,11 +19,6 @@ public class RunTestsResponse : UnityCliLoopToolResponse
         public static readonly string TestFrameworkUnavailableMessage =
             $"run-tests requires the Unity Test Framework package ({UnityCliLoopConstants.PACKAGE_NAME_TEST_FRAMEWORK}). Install it via Package Manager to use test execution.";
 
-        /// <summary>
-        /// Whether test execution was successful
-        /// </summary>
-        public bool Success { get; set; }
-
         /// <summary>
         /// Machine-readable execution status
         /// </summary>

Packages/src/Editor/FirstPartyTools/Screenshot/ScreenshotUseCase.cs

@@ -57,7 +57,12 @@ private async Task<ScreenshotResponse> CaptureRenderingAsync(
                     "CaptureMode.rendering requires PlayMode",
                     correlationId: correlationId
                 );
-                return new ScreenshotResponse();
+                return new ScreenshotResponse
+                {
+                    Success = false,
+                    Message = "Rendering screenshots require PlayMode, but Unity is currently in EditMode.",
+                    NextActions = new[] { "Start PlayMode with `uloop control-play-mode --action Play`, then retry the rendering screenshot." }
+                };
             }
 
             List<UIElementInfo> annotatedElements = new();
@@ -193,7 +198,12 @@ private async Task<ScreenshotResponse> CaptureRenderingAsync(
                     "Play Mode view RenderTexture is not available. Open the Game view or Device Simulator and wait for a frame before retrying.",
                     correlationId: correlationId
                 );
-                return new ScreenshotResponse();
+                return new ScreenshotResponse
+                {
+                    Success = false,
+                    Message = "PlayMode rendering did not produce an image.",
+                    NextActions = new[] { "Open the Game view or Device Simulator, wait for a frame, then retry the rendering screenshot." }
+                };
             }
 
             int width = texture.width;
@@ -296,7 +306,9 @@ private async Task<ScreenshotResponse> CaptureWindowsAsync(
                 );
                 return new ScreenshotResponse
                 {
+                    Success = false,
                     Message = notFoundMessage,
+                    NextActions = new[] { "Open the requested Unity window, then retry the screenshot." }
                 };
             }
 
@@ -399,8 +411,10 @@ internal static ScreenshotResponse CreateTimedOutResult(
 
             return new ScreenshotResponse
             {
+                Success = false,
                 TimedOut = true,
                 Message = message,
+                NextActions = new[] { "Retry the screenshot after Unity finishes rendering the requested frame." },
                 Screenshots = screenshots,
             };
         }

Packages/src/Editor/FirstPartyTools/SimulateKeyboard/SimulateKeyboardResponse.cs

@@ -11,7 +11,6 @@ namespace io.github.hatayama.UnityCliLoop.FirstPartyTools
     /// </summary>
     public class SimulateKeyboardResponse : UnityCliLoopToolResponse
     {
-        public bool Success { get; set; }
         public string Message { get; set; } = "";
         public string Action { get; set; } = "";
         public string? KeyName { get; set; }

Packages/src/Editor/FirstPartyTools/SimulateMouseInput/SimulateMouseInputResponse.cs

@@ -11,7 +11,6 @@ namespace io.github.hatayama.UnityCliLoop.FirstPartyTools
     /// </summary>
     public class SimulateMouseInputResponse : UnityCliLoopToolResponse
     {
-        public bool Success { get; set; }
         public string Message { get; set; } = "";
         public string Action { get; set; } = "";
         public string? Button { get; set; }

Packages/src/Editor/FirstPartyTools/SimulateMouseUi/SimulateMouseUiResponse.cs

@@ -11,7 +11,6 @@ namespace io.github.hatayama.UnityCliLoop.FirstPartyTools
     /// </summary>
     public class SimulateMouseUiResponse : UnityCliLoopToolResponse
     {
-        public bool Success { get; set; }
         public string Message { get; set; } = "";
         public string Action { get; set; } = "";
         public string? HitGameObjectName { get; set; }

Packages/src/Editor/FirstPartyTools/Watch/WatchTools.cs

@@ -40,7 +40,6 @@ public sealed class GetWatchValuesSchema : UnityCliLoopToolSchema
     /// </summary>
     public sealed class WatchResponse : UnityCliLoopToolResponse
     {
-        public bool Success { get; set; } = true;
         public string Id { get; set; } = string.Empty;
         public string Expression { get; set; } = string.Empty;
         public int MaxHistory { get; set; }

Packages/src/Editor/Infrastructure/Api/CompileStatusBridgeCommand.cs

@@ -164,18 +164,20 @@ private static JObject CreateRecoveredCompileResult(
             if (pendingRequest.ForceRecompile)
             {
                 ForceCompileUnknownResult unknownForceCompileResult =
-                    ForceCompileUnknownResult.Create(null);
+                    ForceCompileUnknownResult.Create();
                 message = unknownForceCompileResult.Message;
             }
 
             return new JObject
             {
-                ["Success"] = JValue.CreateNull(),
+                ["Success"] = false,
                 ["ErrorCount"] = JValue.CreateNull(),
                 ["WarningCount"] = JValue.CreateNull(),
                 ["Errors"] = JValue.CreateNull(),
                 ["Warnings"] = JValue.CreateNull(),
                 ["Message"] = message,
+                ["ErrorCode"] = ForceCompileUnknownResult.ErrorCodeText,
+                ["NextActions"] = new JArray(ForceCompileUnknownResult.NextActionText),
                 ["ProjectRoot"] = UnityCliLoopPathResolver.GetProjectRoot()
             };
         }

Packages/src/Editor/ToolContracts/ForceCompileUnknownResult.cs

@@ -5,24 +5,26 @@ namespace io.github.hatayama.UnityCliLoop.ToolContracts
     /// </summary>
     public sealed class ForceCompileUnknownResult
     {
-        public const string MessageText = "Forced full compilation completed. Unity does not return a definitive compile result for this forced full compile path, so fields that Unity did not provide are intentionally null; run get-logs to inspect the compiler output.";
+        public const string MessageText = "Forced full compilation was triggered, but Unity did not provide a definitive result after domain reload.";
+        public const string ErrorCodeText = "COMPILE_RESULT_UNKNOWN";
+        public const string NextActionText = "Wait for domain reload to complete, then run `uloop compile` without --force-recompile to obtain a definitive result.";
 
-        private ForceCompileUnknownResult(bool? success)
+        private ForceCompileUnknownResult()
         {
-            Success = success;
+            Success = false;
             ErrorCount = null;
             WarningCount = null;
             Message = MessageText;
         }
 
-        public bool? Success { get; }
+        public bool Success { get; }
         public int? ErrorCount { get; }
         public int? WarningCount { get; }
         public string Message { get; }
 
-        public static ForceCompileUnknownResult Create(bool? success)
+        public static ForceCompileUnknownResult Create()
         {
-            return new ForceCompileUnknownResult(success);
+            return new ForceCompileUnknownResult();
         }
     }
 }

Packages/src/Editor/ToolContracts/ScreenshotResponse.cs

@@ -37,6 +37,7 @@ public class ScreenshotResponse : UnityCliLoopToolResponse
         public List<ScreenshotInfo> Screenshots { get; set; } = new List<ScreenshotInfo>();
         public bool TimedOut { get; set; }
         public string Message { get; set; } = "";
+        public string[] NextActions { get; set; } = new string[0];
 
         public int ScreenshotCount => Screenshots.Count;
     }

Packages/src/Editor/ToolContracts/UnityCliLoopToolResponse.cs

@@ -5,6 +5,7 @@ namespace io.github.hatayama.UnityCliLoop.ToolContracts
     /// </summary>
     public abstract class UnityCliLoopToolResponse
     {
+        public bool Success { get; set; } = true;
     }
 
     public interface IUnityCliLoopTimingResponse

cli/dispatcher/internal/dispatcher/launch_ready.go

@@ -16,7 +16,7 @@ const (
 	launchReadyMessage               = "Unity CLI Loop is ready."
 	launchAlreadyRunningReadyMessage = "Unity is already running and ready."
 	launchStoppedMessage             = "Unity process stopped."
-	launchNoProcessMessage           = "No Unity process is running for this project."
+	launchNoProcessMessage           = "No matching Unity process was found; it may have already exited."
 )
 
 type launchReadyResponse struct {