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

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

@@ -8,6 +8,7 @@ import {
   type ClientName,
   type ClientInfo,
   type ExecResult,
+  type DebugInfo,
   ClientNotFoundError,
 } from "./types.js";
 
@@ -15,7 +16,8 @@ export interface CliDeps {
   detectClients?: () => ClientInfo[];
   executePrompt?: (
     client: ClientName,
-    prompt: string
+    prompt: string,
+    options?: { timeoutMs?: number; debug?: boolean; onDebug?: (info: DebugInfo) => void }
   ) => Promise<ExecResult>;
   resolveClient?: (
     prompt: string,
@@ -60,6 +62,7 @@ export async function main(
   });
 
   const jsonMode = !args.text;
+  const debug = !!args.debug;
 
   if (args.help) {
     printHelp();
@@ -119,7 +122,11 @@ export async function main(
       typeof args.timeout === "string" ? Number(args.timeout) : config.timeout;
 
     try {
-      const result = await executePrompt(client, prompt, { timeoutMs });
+      const result = await executePrompt(client, prompt, {
+        timeoutMs,
+        debug,
+        onDebug: debug ? (info) => stderrWrite(JSON.stringify(info) + "\n") : undefined,
+      });
       if (jsonMode) {
         console.log(JSON.stringify(result, null, 2));
       } else {
@@ -175,7 +182,11 @@ export async function main(
       typeof args.timeout === "string" ? Number(args.timeout) : config.timeout;
 
     try {
-      const result = await executePrompt(client, prompt, { timeoutMs });
+      const result = await executePrompt(client, prompt, {
+        timeoutMs,
+        debug,
+        onDebug: debug ? (info) => stderrWrite(JSON.stringify(info) + "\n") : undefined,
+      });
       if (jsonMode) {
         console.log(JSON.stringify(result, null, 2));
       } else {

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`, {