feat(S-103): Test-drive and implement --debug diagnostic mode

tools/ai-cli-dispatch/src/execute.ts

@@ -2,7 +2,7 @@ import type { ChildProcess } from "node:child_process";
 import { spawn as defaultSpawn } from "node:child_process";
 import type { PathLike } from "node:fs";
 import { existsSync as defaultExistsSync } from "node:fs";
-import type { ClientName, ExecResult } from "./types.js";
+import type { ClientName, ExecResult, DebugInfo } from "./types.js";
 import { ClientNotFoundError, ExecError } from "./types.js";
 
 const CLIENT_ARGS: Record<ClientName, (prompt: string) => string[]> = {
@@ -14,6 +14,8 @@ const CLIENT_ARGS: Record<ClientName, (prompt: string) => string[]> = {
 export interface ExecuteOptions {
   clientPath?: string;
   timeoutMs?: number;
+  debug?: boolean;
+  onDebug?: (info: DebugInfo) => void;
   spawn?: (command: string, args: string[], options?: { shell?: boolean }) => ChildProcess;
   existsSync?: (path: PathLike) => boolean;
 }
@@ -59,6 +61,7 @@ export async function executePrompt(
     let timedOut = false;
     let stdout = "";
     let stderr = "";
+    let exitSignal: NodeJS.Signals | null = null;
     const startMs = Date.now();
 
     const child = spawnImpl(command, args, {
@@ -86,6 +89,19 @@ export async function executePrompt(
       settled = true;
       clearTimeout(timeout);
       const durationMs = Date.now() - startMs;
+      if (options.debug || options.onDebug) {
+        const debugInfo: DebugInfo = {
+          command,
+          args,
+          pid: child.pid ?? undefined,
+          exitCode: result?.exitCode ?? (err instanceof ExecError ? err.result.exitCode : null),
+          exitSignal,
+          durationMs,
+          stderrLength: stderr.length,
+          stdoutLength: stdout.length,
+        };
+        options.onDebug?.(debugInfo);
+      }
       if (err) {
         if (err instanceof ExecError) {
           err.result.client = client;
@@ -107,7 +123,8 @@ export async function executePrompt(
       }
     });
 
-    child.on("close", (code: number | null) => {
+    child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
+      exitSignal = signal;
       if (timedOut) {
         settle(
           new ExecError(`Execution timed out after ${timeoutMs}ms`, {