@ronkovic/aad 0.3.1 → 0.3.2

package/README.md

@@ -91,6 +91,21 @@ bun install
 bun run dev
 ```
 
+## システム要件
+
+| | RAM | 推奨ワーカー数 |
+|---|---|---|
+| **最小** | 8GB | 1（シングルワーカー） |
+| **推奨** | 16GB | 2（並列ワーカー） |
+
+**メモリ安全機能:**
+- **自動メモリゲート** — 空きメモリが閾値を下回ると新規ワーカーの起動を抑制
+- **シーケンシャルフォールバック** — メモリ不足時に並列実行から逐次実行へ自動切替
+- **グレースフルシャットダウン** — メモリ圧迫時に安全にプロセスを終了
+- **ランタイム監視** — 実行中のメモリ使用量をリアルタイムで監視
+
+> **macOS:** メモリ監視は `vm_stat` ベースで実装されています。Linux環境では `/proc/meminfo` を使用します。
+
 ## クイックスタート
 
 ### 1. 要件ファイルの作成
@@ -303,6 +318,7 @@ aad cleanup --run <run_id> --force
 ## リンク
 
 - [Architecture Documentation](docs/architecture.md)
+- [Case Studies](docs/case-studies/) - Real-world execution examples
 - [Rewrite Plan (Internal)](docs/rewrite-plan/README.md)
 - [Project Guidelines](CLAUDE.md)
 - [Issue Tracker](https://github.com/ronkovic/aad/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ronkovic/aad",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Autonomous Agent Development Orchestrator - Multi-agent TDD pipeline powered by Claude",
   "module": "src/main.ts",
   "type": "module",

package/src/main.ts

@@ -27,7 +27,7 @@ program
   .option("--persist <mode>", "Persistence mode: memory or fs", "memory")
   .option("--debug", "Enable debug logging", false)
   .option("--no-dashboard", "Disable dashboard server")
-  .option("--provider <type>", "Default provider: cli or sdk", "cli");
+  .option("--provider <type>", "Default provider: cli or sdk", "sdk");
 
 // App factory with global options
 const getApp = (): App => {

package/src/modules/claude-provider/claude-provider.port.ts

@@ -15,6 +15,7 @@ export interface ClaudeRequest {
   maxRetries?: number;
   allowedTools?: string[];
   outputFormat?: "text" | "json";
+  jsonSchema?: Record<string, unknown>;  // JSON schema for structured output (when outputFormat="json")
   permissionMode?: "acceptEdits" | "bypassPermissions" | "default" | "delegate" | "dontAsk" | "plan";
   cwd?: string;
   appendSystemPrompt?: string;

package/src/modules/claude-provider/claude-sdk.adapter.ts

@@ -2,6 +2,7 @@ import type { ClaudeProvider, ClaudeRequest, ClaudeResponse } from "./claude-pro
 import type { Config } from "../../shared/config";
 import type pino from "pino";
 import { ClaudeProviderError } from "../../shared/errors";
+import { createMemoryMonitor } from "../../shared/memory-monitor";
 import {
   query,
   type Options,
@@ -26,10 +27,32 @@ export class ClaudeSdkAdapter implements ClaudeProvider {
     const startTime = Date.now();
     const childLogger = this.logger.child({ adapter: "sdk", prompt: request.prompt.slice(0, 50) });
 
+    const memMonitor = createMemoryMonitor({
+      logger: childLogger,
+      checkIntervalMs: 2000,
+      criticalFreeGB: 0.8,
+    });
+
     try {
       childLogger.info("Starting SDK query");
 
       const options = this.buildOptions(request);
+
+      // Memory monitor: abort query if memory becomes critical
+      const memoryAbortController = new AbortController();
+      memMonitor.onCritical(() => {
+        childLogger.error("Critical memory: aborting SDK query");
+        memoryAbortController.abort();
+      });
+
+      // Chain abort controllers if request already has a timeout
+      if (options.abortController) {
+        const originalController = options.abortController;
+        originalController.signal.addEventListener("abort", () => memoryAbortController.abort());
+      }
+      options.abortController = memoryAbortController;
+
+      memMonitor.start();
       const q = query({ prompt: request.prompt, options });
 
       // AsyncGeneratorを消費してClaudeResponseにマッピング
@@ -48,10 +71,21 @@ export class ClaudeSdkAdapter implements ClaudeProvider {
           const textBlocks = assistantMsg.message.content.filter(
             (block: { type: string }) => block.type === "text"
           );
+          
+          childLogger.debug({ 
+            contentLength: assistantMsg.message.content.length, 
+            textBlockCount: textBlocks.length,
+            blockTypes: assistantMsg.message.content.map((b: { type: string }) => b.type)
+          }, "Assistant message content");
+          
           if (textBlocks.length > 0) {
             lastAssistantMessage = textBlocks
               .map((block: { text?: string }) => block.text ?? "")
               .join("\n");
+            childLogger.debug({ 
+              textLength: lastAssistantMessage.length, 
+              textPreview: lastAssistantMessage.slice(0, 300) 
+            }, "Extracted text from assistant message");
           }
           actualModel = assistantMsg.message.model ?? actualModel;
 
@@ -64,8 +98,22 @@ export class ClaudeSdkAdapter implements ClaudeProvider {
           resultMessage = message as SDKResultMessage;
           if (resultMessage.subtype === "success") {
             const successMsg = resultMessage as SDKResultSuccess;
-            lastAssistantMessage = successMsg.result;
+            childLogger.debug({ 
+              sdkResultLength: successMsg.result?.length ?? 0, 
+              sdkResultPreview: successMsg.result?.slice(0, 200) ?? "",
+              hasResult: !!successMsg.result,
+              willOverwrite: !!lastAssistantMessage
+            }, "SDK result message received");
+            
+            // Result message contains the final output; use it if available
+            if (successMsg.result) {
+              lastAssistantMessage = successMsg.result;
+            }
             exitCode = 0;
+            childLogger.debug({ 
+              finalLength: lastAssistantMessage.length, 
+              finalPreview: lastAssistantMessage.slice(0, 200) 
+            }, "Result success");
           } else {
             const errorMsg = resultMessage as SDKResultError;
             error = errorMsg.errors.join("; ");
@@ -74,6 +122,7 @@ export class ClaudeSdkAdapter implements ClaudeProvider {
         }
       }
 
+      memMonitor.stop();
       const duration = Date.now() - startTime;
 
       if (exitCode !== 0) {
@@ -85,14 +134,22 @@ export class ClaudeSdkAdapter implements ClaudeProvider {
 
       childLogger.info({ duration, model: actualModel }, "SDK query completed");
 
-      return {
+      const response: ClaudeResponse = {
         result: lastAssistantMessage,
         exitCode,
         model: actualModel,
         effortLevel: request.effortLevel ?? "medium",
         duration,
       };
+      
+      childLogger.debug({ 
+        responseLength: response.result.length, 
+        responsePreview: response.result.slice(0, 300) 
+      }, "Returning response");
+
+      return response;
     } catch (err) {
+      memMonitor.stop();
       const duration = Date.now() - startTime;
       childLogger.error({ err, duration }, "SDK query error");
 
@@ -121,10 +178,10 @@ export class ClaudeSdkAdapter implements ClaudeProvider {
     // Output Format
     if (request.outputFormat === "json") {
       // JSON出力を要求する場合、schema指定が必要
-      // ここでは汎用的なschemaを使用
+      // jsonSchemaが指定されていればそれを使用、なければ汎用的なschemaを使用
       options.outputFormat = {
         type: "json_schema",
-        schema: {
+        schema: request.jsonSchema ?? {
           type: "object",
           properties: {
             result: { type: "string" },

package/src/modules/cli/__tests__/run.test.ts

@@ -39,9 +39,13 @@ describe("runPipeline", () => {
       logger: {
         info: mock(() => {}),
         error: mock(() => {}),
+        warn: mock(() => {}),
+        debug: mock(() => {}),
         child: mock(() => ({
           info: mock(() => {}),
           error: mock(() => {}),
+          warn: mock(() => {}),
+          debug: mock(() => {}),
         })),
       } as any,
       stores: {

package/src/modules/cli/commands/run.ts

@@ -9,8 +9,10 @@ import type { App } from "../app";
 import { formatProgress, formatTaskTable, createSpinner } from "../output";
 import { createRunId, createWorkerId } from "../../../shared/types";
 import type { WorkspaceInfo } from "../../../shared/types";
-import { getCurrentBranch } from "../../git-workspace";
+import { getCurrentBranch, cleanupOrphanedFromPreviousRuns } from "../../git-workspace";
 import { executeTddPipeline } from "../../task-execution";
+import { checkMemoryAndWarn, waitForMemory } from "../../../shared/memory-check";
+import { installShutdownHandler, isShuttingDown } from "../../../shared/shutdown-handler";
 import {
   detectProjectType,
   detectPackageManager,
@@ -29,14 +31,15 @@ export function createRunCommand(getApp: () => App): Command {
     .option("--persist <mode>", "Persistence mode: memory or fs", "memory")
     .option("--debug", "Enable debug logging")
     .option("--no-dashboard", "Disable dashboard server")
-    .option("--provider <type>", "Default provider: cli or sdk", "cli")
+    .option("--provider <type>", "Default provider: cli or sdk", "sdk")
     .option("--repos <paths>", "Comma-separated repository paths for multi-repo mode")
     .option("--strategy <type>", "Multi-repo strategy: independent or coordinated", "independent")
     .option("--plugins <paths>", "Comma-separated plugin paths to load")
-    .action(async (requirementsPath: string) => {
+    .option("--keep-worktrees", "Keep worktrees and branches after completion (default: auto-cleanup)", false)
+    .action(async (requirementsPath: string, cmdOptions: { keepWorktrees?: boolean }) => {
       try {
         const app = getApp();
-        await runPipeline(app, requirementsPath);
+        await runPipeline(app, requirementsPath, cmdOptions.keepWorktrees ?? false);
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         console.error("Run pipeline failed:", message);
@@ -50,8 +53,8 @@ export function createRunCommand(getApp: () => App): Command {
 /**
  * メインパイプライン実行
  */
-export async function runPipeline(app: App, requirementsPath: string): Promise<void> {
-  const { config, logger, eventBus, planningService, dispatcher, processManager, worktreeManager, providerRegistry, stores } = app;
+export async function runPipeline(app: App, requirementsPath: string, keepWorktrees = false): Promise<void> {
+  const { config, logger, eventBus, planningService, dispatcher, processManager, worktreeManager, providerRegistry, stores, branchManager } = app;
 
   // Validate requirements file exists
   const reqFile = Bun.file(requirementsPath);
@@ -61,6 +64,19 @@ export async function runPipeline(app: App, requirementsPath: string): Promise<v
 
   logger.info({ requirementsPath }, "Starting AAD pipeline");
 
+  // 0. Memory check
+  await checkMemoryAndWarn(logger);
+
+  // 0.5. Cleanup orphaned worktrees/branches from previous runs
+  try {
+    await cleanupOrphanedFromPreviousRuns(worktreeManager, logger);
+  } catch (error) {
+    logger.warn({ error }, "Orphaned worktree cleanup failed (non-critical)");
+  }
+
+  // Semaphore for serializing tasks under memory pressure
+  let memoryGateLock: Promise<void> = Promise.resolve();
+
   // 1. RunId生成 + 現在ブランチ取得
   const runId = createRunId(randomUUID());
   const parentBranch = await getCurrentBranch(process.cwd());
@@ -134,16 +150,60 @@ export async function runPipeline(app: App, requirementsPath: string): Promise<v
     });
   }
 
+  // 4.5. Install graceful shutdown handler
+  installShutdownHandler({
+    runId,
+    stores: { runStore: stores.runStore, taskStore: stores.taskStore },
+    logger,
+  });
+
   // 5. EventBus: task:dispatched → TDDパイプライン起動
   eventBus.on<Extract<import("../../../shared/events").AADEvent, { type: "task:dispatched" }>>(
     "task:dispatched",
     (event) => {
       const taskId = event.taskId;
       const workerId = event.workerId;
+
+      if (isShuttingDown()) {
+        logger.warn({ taskId }, "Shutdown in progress, skipping dispatch");
+        return;
+      }
+
       logger.info({ taskId, workerId }, "Task dispatched, starting TDD pipeline");
 
       void (async () => {
         try {
+          // Memory gate: wait for sufficient memory before dispatch
+          try {
+            const memResult = await waitForMemory(logger);
+            if (memResult.shouldReduceWorkers && config.workers.num > 1) {
+              logger.warn(
+                { freeGB: memResult.freeGB, workers: config.workers.num },
+                "Low memory: serializing task execution",
+              );
+              // Serialize by waiting for previous task's lock
+              const previousLock = memoryGateLock;
+              let releaseLock: () => void;
+              memoryGateLock = new Promise<void>((r) => { releaseLock = r; });
+              await previousLock;
+              // releaseLock will be called at the end of this task
+              try {
+                await runTask();
+              } finally {
+                releaseLock!();
+              }
+              return;
+            }
+          } catch (memError) {
+            // MemoryError → abort task gracefully
+            logger.error({ taskId, error: memError }, "Memory gate failed");
+            eventBus.emit({ type: "task:failed", taskId, error: String(memError) });
+            return;
+          }
+
+          await runTask();
+
+          async function runTask() {
           const task = await stores.taskStore.get(taskId);
           if (!task) {
             throw new Error(`Task not found: ${taskId}`);
@@ -181,6 +241,8 @@ export async function runPipeline(app: App, requirementsPath: string): Promise<v
 
           // 結果をEventBusに通知
           eventBus.emit({ type: "task:completed", taskId, result });
+          } // end runTask
+
         } catch (error) {
           logger.error({ taskId, workerId, error }, "TDD pipeline failed");
           eventBus.emit({ type: "task:failed", taskId, error: String(error) });
@@ -233,6 +295,50 @@ export async function runPipeline(app: App, requirementsPath: string): Promise<v
     logger.info({ runId }, "Pipeline completed successfully");
     console.log("✅ Pipeline completed successfully!");
   }
+
+  // 9. Auto-cleanup worktrees and branches (unless --keep-worktrees)
+  if (!keepWorktrees) {
+    console.log("\n🧹 Cleaning up worktrees and branches...");
+    logger.info({ runId }, "Auto-cleanup started");
+
+    try {
+      // List all worktrees
+      const worktrees = await worktreeManager.listWorktrees();
+      const worktreeBase = `${process.cwd()}/.aad/worktrees`;
+      const runWorktrees = worktrees.filter(
+        (wt) => wt.path.startsWith(worktreeBase) 
+             && wt.branch.includes(runId)  // Check branch name for runId
+             && !wt.path.includes(`parent-${runId}`)  // Keep parent worktree (contains merge results)
+      );
+
+      // Remove worktrees for this run
+      let removed = 0;
+      for (const worktree of runWorktrees) {
+        try {
+          await worktreeManager.removeWorktree(worktree.path, false);
+          removed++;
+          logger.debug({ path: worktree.path }, "Worktree removed");
+        } catch (error) {
+          logger.error({ path: worktree.path, error }, "Failed to remove worktree");
+        }
+      }
+
+      // Prune orphaned worktrees
+      await worktreeManager.pruneWorktrees();
+
+      // Cleanup orphaned branches for this run (force delete merged branches)
+      const deletedBranches = await branchManager.cleanupOrphanBranches(runId, true);
+
+      console.log(`  Removed ${removed} worktree(s)`);
+      console.log(`  Deleted ${deletedBranches.length} branch(es)`);
+      logger.info({ runId, removedWorktrees: removed, deletedBranches: deletedBranches.length }, "Auto-cleanup completed");
+    } catch (error) {
+      logger.error({ runId, error }, "Auto-cleanup failed");
+      console.error("  ⚠️  Cleanup failed (non-critical)");
+    }
+  } else {
+    logger.info({ runId }, "Auto-cleanup skipped (--keep-worktrees)");
+  }
 }
 
 /**

package/src/modules/git-workspace/__tests__/worktree-cleanup.test.ts

@@ -0,0 +1,103 @@
+import { describe, test, expect, beforeEach, mock } from "bun:test";
+import { WorktreeManager, cleanupOrphanedFromPreviousRuns } from "../worktree-manager";
+import { pino } from "pino";
+import type { GitOps } from "../git-exec";
+import type { WorktreeManagerFsOps } from "../worktree-manager";
+
+describe("cleanupOrphanedFromPreviousRuns", () => {
+  let worktreeManager: WorktreeManager;
+  let mockGitOps: GitOps;
+  let mockFsOps: WorktreeManagerFsOps;
+  const logger = pino({ level: "silent" });
+
+  beforeEach(() => {
+    mockGitOps = {
+      gitExec: mock(async (args: string[]) => {
+        if (args[0] === "worktree" && args[1] === "list") {
+          return {
+            stdout: [
+              "worktree /repo",
+              "HEAD abc123",
+              "branch refs/heads/main",
+              "",
+              "worktree /repo/.aad/worktrees/task-001",
+              "HEAD def456",
+              "branch refs/heads/aad/run1/task-001",
+              "",
+              "worktree /repo/.aad/worktrees/task-002",
+              "HEAD ghi789",
+              "branch refs/heads/aad/run1/task-002",
+              "",
+            ].join("\n"),
+            stderr: "",
+            exitCode: 0,
+          };
+        }
+        if (args[0] === "branch" && args[1] === "--list") {
+          return {
+            stdout: "  aad/run1/task-001\n  aad/run1/task-002\n",
+            stderr: "",
+            exitCode: 0,
+          };
+        }
+        return { stdout: "", stderr: "", exitCode: 0 };
+      }),
+      branchExists: mock(async () => false),
+    };
+    mockFsOps = {
+      mkdir: mock(async () => undefined) as any,
+      rm: mock(async () => {}) as any,
+    };
+
+    worktreeManager = new WorktreeManager({
+      repoRoot: "/repo",
+      worktreeBase: "/repo/.aad/worktrees",
+      logger,
+      gitOps: mockGitOps,
+      fsOps: mockFsOps,
+    });
+  });
+
+  test("removes orphaned worktrees and branches", async () => {
+    const result = await cleanupOrphanedFromPreviousRuns(worktreeManager, logger);
+
+    expect(result.removedWorktrees).toBe(2);
+    expect(result.deletedBranches).toBe(2);
+  });
+
+  test("handles empty worktree list gracefully", async () => {
+    mockGitOps.gitExec = mock(async (args: string[]) => {
+      if (args[0] === "worktree" && args[1] === "list") {
+        return { stdout: "worktree /repo\nHEAD abc\nbranch refs/heads/main\n\n", stderr: "", exitCode: 0 };
+      }
+      if (args[0] === "branch" && args[1] === "--list") {
+        return { stdout: "", stderr: "", exitCode: 0 };
+      }
+      return { stdout: "", stderr: "", exitCode: 0 };
+    });
+
+    const result = await cleanupOrphanedFromPreviousRuns(worktreeManager, logger);
+
+    expect(result.removedWorktrees).toBe(0);
+    expect(result.deletedBranches).toBe(0);
+  });
+
+  test("continues if individual worktree removal fails", async () => {
+    let removeCallCount = 0;
+    const originalGitExec = mockGitOps.gitExec;
+    mockGitOps.gitExec = mock(async (args: string[], opts?: any) => {
+      if (args[0] === "worktree" && args[1] === "remove") {
+        removeCallCount++;
+        if (removeCallCount === 1) throw new Error("removal failed");
+        return { stdout: "", stderr: "", exitCode: 0 };
+      }
+      return (originalGitExec as any)(args, opts);
+    });
+
+    const result = await cleanupOrphanedFromPreviousRuns(worktreeManager, logger);
+
+    // First worktree fails, second succeeds
+    expect(result.removedWorktrees).toBe(1);
+    expect(result.deletedBranches).toBe(2);
+  });
+});

package/src/modules/git-workspace/__tests__/worktree-manager.test.ts

@@ -244,4 +244,87 @@ HEAD 789ghi
       );
     });
   });
+
+  describe("cleanupStaleWorktree (via createTaskWorktree)", () => {
+    test("removes stale worktree at target path before creating new one", async () => {
+      const taskId = createTaskId("task-010");
+      const branch = "task/010-stale";
+      const calls: string[][] = [];
+
+      mockGitOps.gitExec = mock(async (args: string[]) => {
+        calls.push(args);
+        return { stdout: "", stderr: "", exitCode: 0 };
+      });
+
+      await worktreeManager.createTaskWorktree(taskId, branch);
+
+      // Should call worktree remove before worktree add
+      const removeIdx = calls.findIndex(c => c[0] === "worktree" && c[1] === "remove");
+      const addIdx = calls.findIndex(c => c[0] === "worktree" && c[1] === "add");
+      expect(removeIdx).toBeGreaterThanOrEqual(0);
+      expect(addIdx).toBeGreaterThan(removeIdx);
+      expect(calls[removeIdx]).toEqual(["worktree", "remove", "/test/worktrees/task-010", "--force"]);
+    });
+
+    test("deletes stale branch before creating new one", async () => {
+      const taskId = createTaskId("task-011");
+      const branch = "task/011-stale-branch";
+      const calls: string[][] = [];
+
+      mockGitOps.gitExec = mock(async (args: string[]) => {
+        calls.push(args);
+        return { stdout: "", stderr: "", exitCode: 0 };
+      });
+
+      await worktreeManager.createTaskWorktree(taskId, branch);
+
+      const branchDeleteCall = calls.find(c => c[0] === "branch" && c[1] === "-D");
+      expect(branchDeleteCall).toBeDefined();
+      expect(branchDeleteCall![2]).toBe(branch);
+
+      // Branch delete should happen before worktree add
+      const branchIdx = calls.indexOf(branchDeleteCall!);
+      const addIdx = calls.findIndex(c => c[0] === "worktree" && c[1] === "add");
+      expect(branchIdx).toBeLessThan(addIdx);
+    });
+
+    test("handles gracefully when no stale worktree exists", async () => {
+      const taskId = createTaskId("task-012");
+      const branch = "task/012-clean";
+
+      // Simulate: worktree remove fails, rm succeeds, prune succeeds, branch -D fails, add succeeds
+      let _callCount = 0;
+      mockGitOps.gitExec = mock(async (args: string[]) => {
+        _callCount++;
+        if (args[1] === "remove") throw new Error("not a worktree");
+        if (args[0] === "branch" && args[1] === "-D") throw new Error("branch not found");
+        return { stdout: "", stderr: "", exitCode: 0 };
+      });
+
+      // Should not throw — cleanup errors are swallowed
+      const result = await worktreeManager.createTaskWorktree(taskId, branch);
+      expect(result).toBe("/test/worktrees/task-012");
+    });
+
+    test("calls git worktree prune during cleanup", async () => {
+      const taskId = createTaskId("task-013");
+      const branch = "task/013-prune";
+      const calls: string[][] = [];
+
+      mockGitOps.gitExec = mock(async (args: string[]) => {
+        calls.push(args);
+        return { stdout: "", stderr: "", exitCode: 0 };
+      });
+
+      await worktreeManager.createTaskWorktree(taskId, branch);
+
+      const pruneCall = calls.find(c => c[0] === "worktree" && c[1] === "prune");
+      expect(pruneCall).toBeDefined();
+
+      // Prune should happen before worktree add
+      const pruneIdx = calls.indexOf(pruneCall!);
+      const addIdx = calls.findIndex(c => c[0] === "worktree" && c[1] === "add");
+      expect(pruneIdx).toBeLessThan(addIdx);
+    });
+  });
 });

package/src/modules/git-workspace/branch-manager.ts

@@ -123,7 +123,7 @@ export class BranchManager {
 
       return result.stdout
         .split("\n")
-        .map((line) => line.trim().replace(/^\* /, ""))
+        .map((line) => line.trim().replace(/^[*+]\s*/, ""))
         .filter((line) => line.length > 0);
     } catch (error) {
       throw new GitWorkspaceError("Failed to list branches", {
@@ -136,13 +136,13 @@ export class BranchManager {
   /**
    * Cleanup orphaned AAD branches (branches without worktrees)
    */
-  async cleanupOrphanBranches(runId?: RunId): Promise<string[]> {
+  async cleanupOrphanBranches(runId?: RunId, force = false): Promise<string[]> {
     // Support both aad/* (slash) and aad-* (hyphen) patterns for backward compatibility
     const patterns = runId
       ? [`aad/${runId as string}/*`, `aad-*-${runId as string}*`]
       : ["aad/*", "aad-*"];
 
-    this.logger?.info({ patterns }, "Cleaning up orphan branches");
+    this.logger?.info({ patterns, force }, "Cleaning up orphan branches");
 
     const deleted: string[] = [];
 
@@ -151,13 +151,13 @@ export class BranchManager {
 
       for (const branch of branches) {
         try {
-          // Try to delete branch (non-force)
-          await this.deleteBranch(branch, false);
+          // Delete branch (force if requested)
+          await this.deleteBranch(branch, force);
           deleted.push(branch);
           this.logger?.info({ branch }, "Deleted orphan branch");
-        } catch (_error) {
-          // Branch still has commits or is checked out, skip
-          this.logger?.debug({ branch }, "Skipping branch (in use or has commits)");
+        } catch (error) {
+          // Branch is checked out in a worktree or deletion failed
+          this.logger?.warn({ branch, error }, "Failed to delete branch");
         }
       }
     }

package/src/modules/git-workspace/index.ts

@@ -1,7 +1,7 @@
 export { gitExec, isGitRepo, getCurrentBranch, branchExists, defaultGitOps } from "./git-exec";
 export type { GitExecOptions, GitExecResult, GitOps } from "./git-exec";
 
-export { WorktreeManager } from "./worktree-manager";
+export { WorktreeManager, cleanupOrphanedFromPreviousRuns } from "./worktree-manager";
 export type { WorktreeManagerOptions, WorktreeManagerFsOps } from "./worktree-manager";
 
 export { BranchManager } from "./branch-manager";