feat: stall detection, worktree cleanup, plan-limits concurrency, reviewer parallel confirmed

- runner.ts: agent stall detection (3min warn, 5min kill via SIGTERM)
- sprint-complete.ts: auto-cleanup orphaned worktrees on sprint complete
- slot-scheduler.ts: reconfigure() for dynamic concurrency from plan limits
- api-client.ts: fetchPlanLimits() for builder/cloud-engineer concurrency
- run-loop.ts: fetch plan limits at startup, start stall detection
- Reviewer already parallel via onExit callbacks (no changes needed)
- 3 new test files (20 tests), 97 total pass

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: recuu-pfeg

src/__tests__/slot-scheduler-reconfig.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from "vitest";
+import { SlotScheduler } from "../slot-scheduler.js";
+
+describe("SlotScheduler.reconfigure", () => {
+  it("increases concurrency by adding new slots", () => {
+    const scheduler = new SlotScheduler([
+      { role: "builder", maxConcurrency: 1 },
+    ]);
+    expect(scheduler.getSlots()).toHaveLength(1);
+
+    scheduler.reconfigure("builder", 3);
+
+    const slots = scheduler.getSlots().filter((s) => s.role === "builder");
+    expect(slots).toHaveLength(3);
+    expect(scheduler.getMaxConcurrency("builder")).toBe(3);
+  });
+
+  it("decreases concurrency by removing idle slots", () => {
+    const scheduler = new SlotScheduler([
+      { role: "builder", maxConcurrency: 3 },
+    ]);
+    expect(scheduler.getSlots().filter((s) => s.role === "builder")).toHaveLength(3);
+
+    scheduler.reconfigure("builder", 1);
+
+    const slots = scheduler.getSlots().filter((s) => s.role === "builder");
+    expect(slots).toHaveLength(1);
+  });
+
+  it("does not remove running slots", () => {
+    const scheduler = new SlotScheduler([
+      { role: "builder", maxConcurrency: 3 },
+    ]);
+
+    // Assign tasks to 2 slots
+    const slot1 = scheduler.acquireSlot("builder")!;
+    scheduler.assignTask(slot1, "task-1");
+    const slot2 = scheduler.acquireSlot("builder")!;
+    scheduler.assignTask(slot2, "task-2");
+
+    // Try to reduce to 1 — only the idle slot should be removed
+    scheduler.reconfigure("builder", 1);
+
+    const slots = scheduler.getSlots().filter((s) => s.role === "builder");
+    expect(slots.length).toBe(2); // 2 running can't be removed
+  });
+
+  it("no-ops when concurrency is unchanged", () => {
+    const scheduler = new SlotScheduler([
+      { role: "builder", maxConcurrency: 2 },
+    ]);
+
+    scheduler.reconfigure("builder", 2);
+
+    expect(scheduler.getSlots().filter((s) => s.role === "builder")).toHaveLength(2);
+  });
+
+  it("getMaxConcurrency returns updated value", () => {
+    const scheduler = new SlotScheduler([
+      { role: "builder", maxConcurrency: 1 },
+    ]);
+    expect(scheduler.getMaxConcurrency("builder")).toBe(1);
+
+    scheduler.reconfigure("builder", 5);
+    expect(scheduler.getMaxConcurrency("builder")).toBe(5);
+  });
+
+  it("getMaxConcurrency returns 0 for unknown role", () => {
+    const scheduler = new SlotScheduler([]);
+    expect(scheduler.getMaxConcurrency("unknown")).toBe(0);
+  });
+
+  it("reconfigures multiple roles independently", () => {
+    const scheduler = new SlotScheduler([
+      { role: "builder", maxConcurrency: 2 },
+      { role: "cloud-engineer", maxConcurrency: 1 },
+    ]);
+
+    scheduler.reconfigure("builder", 3);
+    scheduler.reconfigure("cloud-engineer", 2);
+
+    expect(scheduler.getSlots().filter((s) => s.role === "builder")).toHaveLength(3);
+    expect(scheduler.getSlots().filter((s) => s.role === "cloud-engineer")).toHaveLength(2);
+  });
+});
+
+describe("SlotScheduler plan-limits integration", () => {
+  it("free tier: 1 builder, 1 cloud-engineer", () => {
+    const scheduler = new SlotScheduler([
+      { role: "builder", maxConcurrency: 2 },
+      { role: "cloud-engineer", maxConcurrency: 1 },
+    ]);
+
+    // Simulate free plan limits
+    const limits = { max_builders: 1, max_cloud_engineers: 1 };
+    scheduler.reconfigure("builder", limits.max_builders);
+    scheduler.reconfigure("cloud-engineer", limits.max_cloud_engineers);
+
+    expect(scheduler.getSlots().filter((s) => s.role === "builder")).toHaveLength(1);
+    expect(scheduler.getSlots().filter((s) => s.role === "cloud-engineer")).toHaveLength(1);
+  });
+
+  it("pro tier: 3 builders, 1 cloud-engineer", () => {
+    const scheduler = new SlotScheduler([
+      { role: "builder", maxConcurrency: 2 },
+      { role: "cloud-engineer", maxConcurrency: 1 },
+    ]);
+
+    // Simulate pro plan limits
+    const limits = { max_builders: 3, max_cloud_engineers: 1 };
+    scheduler.reconfigure("builder", limits.max_builders);
+    scheduler.reconfigure("cloud-engineer", limits.max_cloud_engineers);
+
+    expect(scheduler.getSlots().filter((s) => s.role === "builder")).toHaveLength(3);
+    expect(scheduler.acquireSlot("builder")).not.toBeNull();
+  });
+});

src/__tests__/stall-detection.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { TIMEOUTS } from "../constants.js";
+
+describe("stall detection constants", () => {
+  it("AGENT_STALL_WARN is 3 minutes", () => {
+    expect(TIMEOUTS.AGENT_STALL_WARN).toBe(180_000);
+  });
+
+  it("AGENT_STALL_KILL is 5 minutes", () => {
+    expect(TIMEOUTS.AGENT_STALL_KILL).toBe(300_000);
+  });
+
+  it("AGENT_STALL_KILL > AGENT_STALL_WARN", () => {
+    expect(TIMEOUTS.AGENT_STALL_KILL).toBeGreaterThan(TIMEOUTS.AGENT_STALL_WARN);
+  });
+});
+
+describe("stall detection logic", () => {
+  it("detects stall when idle duration exceeds kill threshold", () => {
+    const now = Date.now();
+    const lastActivityAt = now - TIMEOUTS.AGENT_STALL_KILL - 1000;
+    const idleDuration = now - lastActivityAt;
+
+    expect(idleDuration).toBeGreaterThanOrEqual(TIMEOUTS.AGENT_STALL_KILL);
+  });
+
+  it("emits warning when idle duration exceeds warn threshold but not kill", () => {
+    const now = Date.now();
+    const lastActivityAt = now - TIMEOUTS.AGENT_STALL_WARN - 1000;
+    const idleDuration = now - lastActivityAt;
+
+    expect(idleDuration).toBeGreaterThanOrEqual(TIMEOUTS.AGENT_STALL_WARN);
+    expect(idleDuration).toBeLessThan(TIMEOUTS.AGENT_STALL_KILL);
+  });
+
+  it("does not trigger when activity is recent", () => {
+    const now = Date.now();
+    const lastActivityAt = now - 10_000; // 10 seconds ago
+    const idleDuration = now - lastActivityAt;
+
+    expect(idleDuration).toBeLessThan(TIMEOUTS.AGENT_STALL_WARN);
+  });
+
+  it("resets stall warning on new activity", () => {
+    let stallWarned = true;
+    // Simulate stdout data arriving
+    const lastActivityAt = Date.now();
+    stallWarned = false;
+
+    expect(stallWarned).toBe(false);
+    expect(lastActivityAt).toBeGreaterThan(0);
+  });
+});

src/__tests__/worktree-cleanup.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { parseWorktreeList } from "../commands/sprint-complete.js";
+
+describe("parseWorktreeList", () => {
+  it("parses porcelain output with branches", () => {
+    const output = `worktree /Users/test/repo
+branch refs/heads/main
+
+worktree /Users/test/repo/.worktrees/agent-builder-1-abc12345
+branch refs/heads/agent/builder-1-abc12345
+
+worktree /Users/test/repo/.worktrees/agent-builder-2-def67890
+branch refs/heads/agent/builder-2-def67890
+
+`;
+    const result = parseWorktreeList(output);
+
+    expect(result).toHaveLength(3);
+    expect(result[0]).toEqual({ path: "/Users/test/repo", branch: "refs/heads/main" });
+    expect(result[1]).toEqual({
+      path: "/Users/test/repo/.worktrees/agent-builder-1-abc12345",
+      branch: "refs/heads/agent/builder-1-abc12345",
+    });
+    expect(result[2]).toEqual({
+      path: "/Users/test/repo/.worktrees/agent-builder-2-def67890",
+      branch: "refs/heads/agent/builder-2-def67890",
+    });
+  });
+
+  it("handles entries without branches (detached HEAD)", () => {
+    const output = `worktree /Users/test/repo
+branch refs/heads/main
+
+worktree /Users/test/repo/.worktrees/detached
+HEAD abc1234567890
+detached
+
+`;
+    const result = parseWorktreeList(output);
+
+    expect(result).toHaveLength(2);
+    expect(result[0].branch).toBe("refs/heads/main");
+    expect(result[1].branch).toBeNull();
+  });
+
+  it("returns empty for empty input", () => {
+    expect(parseWorktreeList("")).toEqual([]);
+  });
+
+  it("identifies agent worktree branches", () => {
+    const output = `worktree /repo
+branch refs/heads/main
+
+worktree /repo/.worktrees/agent-builder-abc
+branch refs/heads/agent/builder-abc
+
+worktree /repo/.worktrees/feature-branch
+branch refs/heads/feature/new-feature
+
+`;
+    const result = parseWorktreeList(output);
+    const agentWorktrees = result.filter((w) => w.branch?.startsWith("refs/heads/agent/"));
+
+    expect(agentWorktrees).toHaveLength(1);
+    expect(agentWorktrees[0].branch).toBe("refs/heads/agent/builder-abc");
+  });
+});

src/api-client.ts

@@ -115,6 +115,13 @@ export interface ApiClient {
   putAgentMemory(agentName: string, key: string, data: { type: string; content: string; shared?: boolean; tags?: string }): Promise<void>;
   fetchRelevantFailures(): Promise<Array<{ summary: string; failure_type: string; agent_name: string | null; created_at: string }>>;
   recordFailure(data: { task_id: string; failure_type: string; summary: string; agent_name?: string; sprint?: number; review_comment?: string; files_involved?: string }): Promise<void>;
+  /** Fetch plan limits (max concurrent builders, etc.) */
+  fetchPlanLimits(): Promise<PlanLimits>;
+}
+
+export interface PlanLimits {
+  max_builders: number;
+  max_cloud_engineers: number;
 }
 
 /** Create standard auth headers for API requests. */
@@ -368,5 +375,16 @@ export function createApiClient(apiUrl: string, apiKey: string): ApiClient {
         });
       } catch { /* best-effort */ }
     },
+
+    async fetchPlanLimits(): Promise<PlanLimits> {
+      try {
+        const res = await fetch(`${apiUrl}/api/v1/workspace/plan-limits`, { headers });
+        if (res.ok) {
+          return (await res.json()) as PlanLimits;
+        }
+      } catch { /* non-fatal */ }
+      // Default: free tier limits
+      return { max_builders: 1, max_cloud_engineers: 1 };
+    },
   };
 }

src/commands/run-loop.ts

@@ -95,13 +95,24 @@ export async function runLoop(cliArgs: CliArgs, runner: AgentRunner, shutdownSta
 
   const POLL_INTERVAL_MS = INTERVALS.POLL;
 
-  // Parallel agent slots
+  // Parallel agent slots — start with defaults, then reconfigure from plan limits
   const { SlotScheduler } = await import("../slot-scheduler.js");
   const scheduler = new SlotScheduler([
     { role: "builder", maxConcurrency: 2 },
     { role: "cloud-engineer", maxConcurrency: 1 },
   ]);
 
+  // Fetch plan limits and reconfigure scheduler
+  try {
+    const limits = await api.fetchPlanLimits();
+    scheduler.reconfigure("builder", limits.max_builders);
+    scheduler.reconfigure("cloud-engineer", limits.max_cloud_engineers);
+    ui.info(`[plan] Builder concurrency: ${limits.max_builders}, Cloud-engineer: ${limits.max_cloud_engineers}`);
+  } catch { /* non-fatal — use defaults */ }
+
+  // Start stall detection for agent processes
+  runner.startStallDetection();
+
   while (!shutdownState.shuttingDown) {
     try {
       sprintData = await api.fetchSprintData();

src/commands/shutdown.ts

@@ -27,6 +27,7 @@ export function setupShutdownHandlers(runner: AgentRunner, state: ShutdownState)
     ui.warn("Shutting down...");
     state.activeWsServer?.stop().catch(() => {});
     state.activeManager?.stop();
+    runner.stopStallDetection();
     for (const agent of runner.status()) { ui.info(`Stopping agent: ${agent.name}`); runner.stop(agent.name); }
     setTimeout(() => { ui.shutdown(); process.exit(0); }, 3000);
   };

src/commands/sprint-complete.ts

@@ -2,11 +2,34 @@
  * Sprint complete command
  */
 
-import { createApiClient } from "../api-client.js";
+import { createApiClient, createAuthHeaders } from "../api-client.js";
 import { logError, CLI_ERR } from "../error-logger.js";
 import * as ui from "../ui.js";
 import { execSync } from "node:child_process";
 
+interface WorktreeEntry {
+  path: string;
+  branch: string | null;
+}
+
+/**
+ * Parse `git worktree list --porcelain` output into structured entries.
+ */
+export function parseWorktreeList(output: string): WorktreeEntry[] {
+  const entries: WorktreeEntry[] = [];
+  let current: Partial<WorktreeEntry> = {};
+  for (const line of output.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      if (current.path) entries.push({ path: current.path, branch: current.branch ?? null });
+      current = { path: line.slice("worktree ".length) };
+    } else if (line.startsWith("branch ")) {
+      current.branch = line.slice("branch ".length);
+    }
+  }
+  if (current.path) entries.push({ path: current.path, branch: current.branch ?? null });
+  return entries;
+}
+
 export async function handleSprintComplete(apiUrl: string, apiKey: string, push: boolean): Promise<void> {
   const api = createApiClient(apiUrl, apiKey);
   ui.intro();
@@ -47,7 +70,47 @@ export async function handleSprintComplete(apiUrl: string, apiKey: string, push:
       process.exit(1);
     }
   }
-  // Proposals are now triggered at retrospective phase, not on complete
+  // Clean up orphaned worktrees
+  try {
+    const worktreeOutput = execSync("git worktree list --porcelain", { stdio: "pipe" }).toString();
+    const worktrees = parseWorktreeList(worktreeOutput);
+    let cleaned = 0;
+    for (const wt of worktrees) {
+      if (wt.branch?.startsWith("refs/heads/agent/")) {
+        try {
+          execSync(`git worktree remove "${wt.path}" --force`, { stdio: "pipe" });
+          cleaned++;
+        } catch { /* non-fatal — worktree may be in use */ }
+        try {
+          const branchName = wt.branch.replace("refs/heads/", "");
+          execSync(`git branch -D "${branchName}"`, { stdio: "pipe" });
+        } catch { /* non-fatal */ }
+      }
+    }
+    execSync("git worktree prune", { stdio: "pipe" });
+    if (cleaned > 0) ui.step(`Cleaned up ${cleaned} orphaned worktree(s)`);
+  } catch (err) {
+    ui.warn(`Failed to clean up worktrees: ${err instanceof Error ? err.message : err}`);
+  }
+
+  // Rule scoring: apply decay and report stale/remove rules
+  try {
+    const decayRes = await fetch(`${apiUrl}/api/v1/rule-evaluations/decay`, {
+      method: "POST",
+      headers: createAuthHeaders(apiKey),
+      body: JSON.stringify({ sprint_number: sprint.number }),
+    });
+    if (decayRes.ok) {
+      const decay = await decayRes.json() as { rules_decayed: number; decayed: Array<{ rule_id: string; score: number; status: string }> };
+      if (decay.rules_decayed > 0) {
+        ui.info(`[rule-eval] Decayed ${decay.rules_decayed} rule(s)`);
+        const stale = decay.decayed.filter((r) => r.status === "stale");
+        const remove = decay.decayed.filter((r) => r.status === "remove");
+        if (stale.length > 0) ui.warn(`[rule-eval] ${stale.length} rule(s) stale — consider reviewing`);
+        if (remove.length > 0) ui.warn(`[rule-eval] ${remove.length} rule(s) below threshold — candidates for removal`);
+      }
+    }
+  } catch { /* non-fatal */ }
 
   ui.outro(`Sprint #${sprint.number} complete`);
 }