feat: add debug_issue tool handler

AGENT_HANDOFF.md

@@ -42,16 +42,17 @@ Build the MCP tool handlers that:
 - Task 4.1 — ask_chatgpt handler (`src/tools/ask-chatgpt.js`, `test/tools/ask-chatgpt.test.js`) ✅
 - Task 4.2 — review_plan handler (`src/tools/review-plan.js`, `test/tools/review-plan.test.js`) ✅
 - Task 4.3 — review_code handler (`src/tools/review-code.js`, `test/tools/review-code.test.js`) ✅
+- Task 4.4 — debug_issue tool handler (`src/tools/debug-issue.js`, `test/tools/debug-issue.test.js`) ✅
 
 ## Next Pending
 
-### Task 4.3 - review_code tool handler ✅
+### Task 4.4 - debug_issue tool handler ✅
 
-Built `src/tools/review-code.js` with dependency-injected `handleReviewCode(input, deps)` and 28 orchestration-only tests in `test/tools/review-code.test.js`. Followed the same pattern as 4.1 and 4.2. All 28 tests pass.
+Built `src/tools/debug-issue.js` with dependency-injected `handleDebugIssue(input, deps)` and 28 orchestration-only tests in `test/tools/debug-issue.test.js`. Followed the same pattern as 4.1, 4.2, and 4.3. All 28 tests pass.
 
 ### Next Pending
 
-- Task 4.4 — debug_issue tool handler (`src/tools/debug-issue.js`, `test/tools/debug-issue.test.js`)
+- Task 4.5 — architecture_review tool handler (`src/tools/architecture-review.js`, `test/tools/architecture-review.test.js`)
 
 ## General Rules
 

PROJECT_STATE.md

@@ -7,7 +7,7 @@ ChatGPT MCP Server
 ## Status
 
 Planning complete.
-Phase 0 complete. Phase 1 complete. Phase 2 complete. Phase 3 complete. Task 4.1 complete. Task 4.2 complete. Task 4.3 complete.
+Phase 0 complete. Phase 1 complete. Phase 2 complete. Phase 3 complete. Task 4.1 complete. Task 4.2 complete. Task 4.3 complete. Task 4.4 complete.
 
 ## Current Phase
 
@@ -34,6 +34,7 @@ Phase 4 - Tool Handlers
 - Task 4.1 — ask_chatgpt MCP tool handler (`src/tools/ask-chatgpt.js`, `test/tools/ask-chatgpt.test.js`) ✅
 - Task 4.2 — review_plan MCP tool handler (`src/tools/review-plan.js`, `test/tools/review-plan.test.js`) ✅
 - Task 4.3 — review_code MCP tool handler (`src/tools/review-code.js`, `test/tools/review-code.test.js`) ✅
+- Task 4.4 — debug_issue tool handler (`src/tools/debug-issue.js`, `test/tools/debug-issue.test.js`) ✅
 
 ## Phase 3 Completion Summary
 
@@ -96,8 +97,7 @@ Implemented `src/tools/review-code.js` with dependency-injected handler and 28 o
 - 28 tests mirroring 4.1/4.2 structure with one test verifying buildReviewCodePrompt is called with budget.input
 
 **Next pending task:**
-- Task 4.4 — debug_issue tool handler (`src/tools/debug-issue.js`, `test/tools/debug-issue.test.js`)
+- Task 4.5 — architecture_review tool handler (`src/tools/architecture-review.js`, `test/tools/architecture-review.test.js`)
 
 **Not done yet (Phase 4):**
 - No MCP tool registration
-- Other tool handlers (debug_issue, architecture_review)

TASKS.md

@@ -329,7 +329,7 @@ Create `src/tools/review-plan.js` and `test/tools/review-plan.test.js`.
 
 Status: ✅ Complete
 
-### Task 4.3 - review_code tool handler (NEXT)
+### Task 4.3 - review_code tool handler ✅
 
 Create `src/tools/review-code.js` and `test/tools/review-code.test.js`.
 
@@ -357,6 +357,21 @@ Create `src/tools/debug-issue.js` and `test/tools/debug-issue.test.js`.
 - OpenAI errors pass through `String(err)` unchanged (no wrapping/reformatting).
 - Mirror 4.1/4.2/4.3 structure: ~28 orchestration-only tests covering the same test categories.
 
+Status: ✅ Complete
+
+### Task 4.5 - architecture_review tool handler
+
+Create `src/tools/architecture-review.js` and `test/tools/architecture-review.test.js`.
+
+**Requirements:**
+- Export `handleArchitectureReview(input, deps)` as standalone dependency-injected function.
+- Execution order: validateToolInput → loadConfig → checkContextBudget → buildArchitectureReviewPrompt → createOpenAIClient → sendOpenAIResponse.
+- Inject only 3 external deps: `loadConfig`, `createOpenAIClient`, `sendOpenAIResponse`. Internal utilities imported directly.
+- If budget check fails (`ok: false`), immediately return that result — do not call buildArchitectureReviewPrompt or create client.
+- All paths return structured `{ ok, answer|error, warnings }` — never throws to caller.
+- OpenAI errors pass through `String(err)` unchanged (no wrapping/reformatting).
+- Mirror 4.1/4.2/4.3/4.4 structure: ~28 orchestration-only tests covering the same test categories.
+
 Status: ⬜ Pending
 
 ---

src/tools/debug-issue.js

@@ -1 +1,78 @@
-// debug_issue tool handler.
+// Tool handler for the debug_issue MCP tool.
+
+import { validateToolInput } from "./schemas.js";
+import { checkContextBudget } from "../utils/context-budget.js";
+import { buildDebugIssuePrompt } from "../prompts/debug-issue.js";
+
+/**
+ * Handle the debug_issue MCP tool.
+ *
+ * Orchestration order: validate -> config -> budget -> prompt -> client -> response.
+ * All external dependencies injected via deps. Internal utilities imported directly.
+ * No throws escape — all paths return structured results.
+ *
+ * @param {unknown} input
+ *   Raw tool input per ARCHITECTURE.md §7 schema.
+ * @param {{
+ *   loadConfig: () => object,
+ *   createOpenAIClient: (config: object) => any,
+ *   sendOpenAIResponse: (client: any, params: object) => Promise<any>
+ * }} deps
+ *   Injected external dependencies.
+ * @returns {Promise<{ ok: true, answer: string, warnings: string[] } | { ok: false, error: string, warnings: string[] }>}
+ */
+export async function handleDebugIssue(input, deps) {
+  // --- 1. Validate input (before anything else) ---
+
+  const validation = validateToolInput(input);
+  if (!validation.ok) {
+    return { ok: false, error: validation.errors.join(" | "), warnings: [] };
+  }
+
+  // --- 2. Load config ---
+
+  let config;
+  try {
+    config = deps.loadConfig();
+  } catch (err) {
+    return { ok: false, error: String(err), warnings: [] };
+  }
+
+  // --- 3. Context budget check ---
+
+  const budget = checkContextBudget(validation.data, config);
+  if (!budget.ok) {
+    return { ok: false, error: budget.error, warnings: budget.warnings };
+  }
+
+  // --- 4. Build prompt ---
+
+  const promptMessages = buildDebugIssuePrompt(budget.input);
+
+  // --- 5. Create OpenAI client ---
+
+  let client;
+  try {
+    client = deps.createOpenAIClient(config);
+  } catch (err) {
+    return { ok: false, error: String(err), warnings: [] };
+  }
+
+  // --- 6. Send to OpenAI ---
+
+  let aiResult;
+  try {
+    aiResult = await deps.sendOpenAIResponse(client, {
+      input: [{ role: "system", content: promptMessages }],
+      model: config.openaiModel,
+      temperature: config.temperature,
+      maxOutputTokens: config.maxOutputTokens,
+    });
+  } catch (err) {
+    return { ok: false, error: String(err), warnings: [] };
+  }
+
+  // --- 7. Success ---
+
+  return { ok: true, answer: aiResult.content, warnings: budget.warnings };
+}

test/tools/debug-issue.test.js

@@ -0,0 +1,453 @@
+import { describe, it, expect, vi } from "vitest";
+
+// Module-level mock capture for buildDebugIssuePrompt integration testing.
+const buildDebugIssuePromptCalls = [];
+
+vi.mock("../../src/prompts/debug-issue.js", async () => ({
+  buildDebugIssuePrompt: vi.fn((input) => {
+    buildDebugIssuePromptCalls.push(input);
+    return "mocked debug issue prompt";
+  }),
+}));
+
+// Import after the mock is registered (hoisted by vitest).
+const { handleDebugIssue } = await import("../../src/tools/debug-issue.js");
+
+const mockConfig = {
+  openaiApiKey: "sk-test-key",
+  openaiModel: "gpt-5.1",
+  temperature: 0.2,
+  maxOutputTokens: 2000,
+  logLevel: "info",
+  enableFileContext: false,
+  contextDir: "./context",
+  maxInputChars: 30000,
+  maxFileChars: 12000,
+  maxFiles: 5,
+  maxLogChars: 10000,
+  redactSecrets: true,
+};
+
+function makeValidInput(question) {
+  return { question };
+}
+
+// --- Success path ---
+
+describe("success path", () => {
+  it("returns ok:true with answer on full happy flow", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => mockConfig);
+    const createOpenAIClient = vi.fn(() => ({ responses: { create: vi.fn() } }));
+    const sendOpenAIResponse = vi.fn(async () => ({ content: "OK" }));
+
+    const result = await handleDebugIssue(makeValidInput("Debug my issue"), {
+      loadConfig, createOpenAIClient, sendOpenAIResponse,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.answer).toBe("OK");
+    expect(result.warnings).toEqual([]);
+  });
+
+  it("propagates budget warnings through to success result", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const trimmedBudget = { ...mockConfig, maxInputChars: 50 };
+    const loadConfig = vi.fn(() => trimmedBudget);
+    const createOpenAIClient = vi.fn(() => ({ responses: { create: vi.fn() } }));
+    const sendOpenAIResponse = vi.fn(async () => ({ content: "OK" }));
+
+    const result = await handleDebugIssue(makeValidInput("hi"), {
+      loadConfig, createOpenAIClient, sendOpenAIResponse,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(Array.isArray(result.warnings)).toBe(true);
+  });
+});
+
+// --- Validation failure (short-circuit before config) ---
+
+describe("validation failure", () => {
+  it("returns structured error when question is missing", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn();
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue({}, { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.ok).toBe(false);
+    expect(typeof result.error).toBe("string");
+    expect(result.warnings).toEqual([]);
+  });
+
+  it("short-circuits — no other deps called", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn();
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    await handleDebugIssue({ foo: "bar" }, { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(loadConfig).not.toHaveBeenCalled();
+    expect(createOpenAIClient).not.toHaveBeenCalled();
+    expect(sendOpenAIResponse).not.toHaveBeenCalled();
+  });
+
+  it("returns structured error when question is empty string", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn();
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue({ question: "" }, { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.ok).toBe(false);
+    expect(typeof result.error).toBe("string");
+    expect(result.warnings).toEqual([]);
+  });
+
+  it("returns structured error when question is wrong type", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn();
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue({ question: 123 }, { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.ok).toBe(false);
+    expect(typeof result.error).toBe("string");
+    expect(result.warnings).toEqual([]);
+  });
+});
+
+// --- Config failure ---
+
+describe("config failure", () => {
+  it("returns structured error when loadConfig throws", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => { throw new Error("OPENAI_API_KEY is missing."); });
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain("OPENAI_API_KEY is missing");
+  });
+
+  it("short-circuits — no client or response calls after config failure", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => { throw new Error("No key."); });
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(createOpenAIClient).not.toHaveBeenCalled();
+    expect(sendOpenAIResponse).not.toHaveBeenCalled();
+  });
+
+  it("passes original error message", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => { throw new Error("OPENAI_API_KEY is missing."); });
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.error).toBe("Error: OPENAI_API_KEY is missing.");
+  });
+});
+
+// --- Budget failure (short-circuit before prompt/client) ---
+
+describe("budget failure", () => {
+  it("returns structured error with budget warnings when input exceeds budget", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const tinyBudget = { ...mockConfig, maxInputChars: 0 };
+    const loadConfig = vi.fn(() => tinyBudget);
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.ok).toBe(false);
+    expect(typeof result.error).toBe("string");
+    expect(Array.isArray(result.warnings)).toBe(true);
+  });
+
+  it("short-circuits — no prompt built, no client created, no response sent", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const tinyBudget = { ...mockConfig, maxInputChars: 0 };
+    const loadConfig = vi.fn(() => tinyBudget);
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(createOpenAIClient).not.toHaveBeenCalled();
+    expect(sendOpenAIResponse).not.toHaveBeenCalled();
+  });
+
+  it("passes budget warnings through to the error result", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const tinyBudget = { ...mockConfig, maxInputChars: 0 };
+    const loadConfig = vi.fn(() => tinyBudget);
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue(
+      { question: "x", context: "a".repeat(20) },
+      { loadConfig, createOpenAIClient, sendOpenAIResponse },
+    );
+
+    expect(result.ok).toBe(false);
+    expect(Array.isArray(result.warnings)).toBe(true);
+  });
+});
+
+// --- Client creation failure ---
+
+describe("client creation failure", () => {
+  it("returns structured error when createOpenAIClient throws", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => mockConfig);
+    const createOpenAIClient = vi.fn(() => { throw new Error("Invalid config."); });
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.ok).toBe(false);
+    expect(typeof result.error).toBe("string");
+    expect(result.warnings).toEqual([]);
+  });
+
+  it("short-circuits — no response sent after client failure", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => mockConfig);
+    const createOpenAIClient = vi.fn(() => { throw new Error("Invalid config."); });
+    const sendOpenAIResponse = vi.fn();
+
+    await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(sendOpenAIResponse).not.toHaveBeenCalled();
+  });
+
+  it("passes original error message unchanged", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => mockConfig);
+    const createOpenAIClient = vi.fn(() => { throw new Error("Invalid config."); });
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.error).toBe("Error: Invalid config.");
+  });
+});
+
+// --- OpenAI failure (pass-through) ---
+
+describe("OpenAI failure", () => {
+  it("passes through err.message unchanged", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => mockConfig);
+    const createOpenAIClient = vi.fn(() => ({ responses: { create: vi.fn() } }));
+    const sendOpenAIResponse = vi.fn().mockRejectedValue(new Error("API key invalid."));
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe("Error: API key invalid.");
+    expect(result.warnings).toEqual([]);
+  });
+
+  it("short-circuits — no extra processing after API failure", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => mockConfig);
+    const createOpenAIClient = vi.fn(() => ({ responses: { create: vi.fn() } }));
+    const sendOpenAIResponse = vi.fn().mockRejectedValue(new Error("rate limit"));
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe("Error: rate limit");
+  });
+
+  it("does not wrap or reformat the error", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => mockConfig);
+    const createOpenAIClient = vi.fn(() => ({ responses: { create: vi.fn() } }));
+    const sendOpenAIResponse = vi.fn().mockRejectedValue(new Error("429 Too Many Requests"));
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.error).toBe("Error: 429 Too Many Requests");
+  });
+});
+
+// --- Dependency call order ---
+
+describe("dependency call order", () => {
+  it("calls deps in correct order: config -> client -> response", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const callLog = [];
+    const loadConfig = vi.fn(() => { callLog.push("config"); return mockConfig; });
+    const createOpenAIClient = vi.fn(() => { callLog.push("client"); return { responses: { create: vi.fn() } }; });
+    const sendOpenAIResponse = vi.fn(async () => { callLog.push("response"); return { content: "OK" }; });
+
+    await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(callLog).toEqual(["config", "client", "response"]);
+  });
+});
+
+// --- buildDebugIssuePrompt integration ---
+
+describe("buildDebugIssuePrompt integration", () => {
+  it("calls buildDebugIssuePrompt and receives budget.input as argument", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => mockConfig);
+    const createOpenAIClient = vi.fn(() => ({ responses: { create: vi.fn() } }));
+    const sendOpenAIResponse = vi.fn(async () => ({ content: "OK" }));
+
+    await handleDebugIssue(makeValidInput("test question"), {
+      loadConfig, createOpenAIClient, sendOpenAIResponse,
+    });
+
+    // Verify buildDebugIssuePrompt was called (once) with the trimmed input from checkContextBudget.
+    expect(buildDebugIssuePromptCalls.length).toBe(1);
+    const captured = buildDebugIssuePromptCalls[0];
+    expect(typeof captured).toBe("object");
+    expect(captured.question).toBe("test question");
+  });
+});
+
+// --- No throws escaping ---
+
+describe("no throws escaping", () => {
+  it("returns structured result when sendOpenAIResponse throws null", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => mockConfig);
+    const createOpenAIClient = vi.fn(() => ({ responses: { create: vi.fn() } }));
+    const sendOpenAIResponse = vi.fn().mockRejectedValue(null);
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.ok).toBe(false);
+    expect(typeof result.error).toBe("string");
+  });
+
+  it("returns structured result when loadConfig throws non-Error", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => { throw "string error"; });
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.ok).toBe(false);
+    expect(typeof result.error).toBe("string");
+  });
+});
+
+// --- Warning propagation ---
+
+describe("warning propagation", () => {
+  it("includes budget warnings in success result when budget passes with warnings", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const trimmedBudget = { ...mockConfig, maxInputChars: 50 };
+    const loadConfig = vi.fn(() => trimmedBudget);
+    const createOpenAIClient = vi.fn(() => ({ responses: { create: vi.fn() } }));
+    const sendOpenAIResponse = vi.fn(async () => ({ content: "OK" }));
+
+    const result = await handleDebugIssue(
+      { question: "hi", context: "x".repeat(49) },
+      { loadConfig, createOpenAIClient, sendOpenAIResponse },
+    );
+
+    expect(result.ok).toBe(true);
+    expect(Array.isArray(result.warnings)).toBe(true);
+  });
+
+  it("includes budget warnings in failure result when budget fails", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const emptyBudget = { ...mockConfig, maxInputChars: 0 };
+    const loadConfig = vi.fn(() => emptyBudget);
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(result.ok).toBe(false);
+    expect(Array.isArray(result.warnings)).toBe(true);
+  });
+});
+
+// --- Result shape ---
+
+describe("result shape", () => {
+  it("returns exactly { ok, answer, warnings } on success", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => mockConfig);
+    const createOpenAIClient = vi.fn(() => ({ responses: { create: vi.fn() } }));
+    const sendOpenAIResponse = vi.fn(async () => ({ content: "OK" }));
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(Object.keys(result).sort()).toEqual(["answer", "ok", "warnings"]);
+    expect(result.ok).toBe(true);
+    expect(typeof result.answer).toBe("string");
+    expect(Array.isArray(result.warnings)).toBe(true);
+  });
+
+  it("returns exactly { ok, error, warnings } on failure", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => { throw new Error("fail"); });
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    const result = await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(Object.keys(result).sort()).toEqual(["error", "ok", "warnings"]);
+    expect(result.ok).toBe(false);
+    expect(typeof result.error).toBe("string");
+    expect(Array.isArray(result.warnings)).toBe(true);
+  });
+});
+
+// --- Short-circuit behavior ---
+
+describe("short-circuit behavior", () => {
+  it("stops at first failure without calling downstream deps", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => mockConfig);
+    const createOpenAIClient = vi.fn(() => ({ responses: { create: vi.fn() } }));
+    const sendOpenAIResponse = vi.fn().mockRejectedValue(new Error("boom"));
+
+    await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(loadConfig).toHaveBeenCalledTimes(1);
+    expect(createOpenAIClient).toHaveBeenCalledTimes(1);
+    expect(sendOpenAIResponse).toHaveBeenCalledTimes(1);
+  });
+
+  it("stops at config failure without calling downstream deps", async () => {
+    buildDebugIssuePromptCalls.length = 0;
+
+    const loadConfig = vi.fn(() => { throw new Error("fail"); });
+    const createOpenAIClient = vi.fn();
+    const sendOpenAIResponse = vi.fn();
+
+    await handleDebugIssue(makeValidInput("hi"), { loadConfig, createOpenAIClient, sendOpenAIResponse });
+    expect(loadConfig).toHaveBeenCalledTimes(1);
+    expect(createOpenAIClient).not.toHaveBeenCalled();
+    expect(sendOpenAIResponse).not.toHaveBeenCalled();
+  });
+});