ralph-review 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-review",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Orchestrating coding agents for code review, verification and fixing via the ralph loop.",
   "license": "MIT",
   "type": "module",
@@ -53,16 +53,16 @@
     "publish:recover": "bun run scripts/publish.ts --recover",
     "publish:recover:execute": "bun run scripts/publish.ts --recover --execute",
     "rr": "bun run src/cli.ts",
-    "test": "AGENT=1 bun test",
-    "prepublishOnly": "bun test",
+    "test": "AGENT=1 bun test --max-concurrency=1",
+    "prepublishOnly": "bun test --max-concurrency=1",
     "typecheck": "tsc --noEmit",
     "knip": "knip-bun",
     "check-duplicates": "bunx jscpd src tests --exitCode 1 --reporters ai",
     "lint": "biome check --write .",
     "lint:ci": "biome ci .",
     "lint-staged": "lint-staged",
-    "check": "bun run typecheck && bun run knip && bun run lint && bun run check-duplicates && AGENT=1 bun test --coverage",
-    "check:ci": "bun run typecheck && bun run knip && bun run lint:ci && bun run check-duplicates && AGENT=1 bun test --coverage",
+    "check": "bun run typecheck && bun run knip && bun run lint && bun run check-duplicates && AGENT=1 bun test --max-concurrency=1 --coverage",
+    "check:ci": "bun run typecheck && bun run knip && bun run lint:ci && bun run check-duplicates && AGENT=1 bun test --max-concurrency=1 --coverage",
     "prepare": "husky && bun run setup-hooks",
     "setup-hooks": "bun -e 'await Bun.write(\".husky/pre-commit\", \"#!/usr/bin/env sh\\n\\nbun run knip && bun run lint-staged\\n\")' && chmod +x .husky/pre-commit"
   },

package/src/commands/apply.ts

@@ -1,20 +1,35 @@
-import * as p from "@clack/prompts";
 import { resolvePendingHandoffSelection } from "@/commands/handoff-selection";
 import {
   createInteractiveCommandDeps,
+  createPromptDeps,
   type InteractiveCommandDeps,
+  type PromptDeps,
 } from "@/commands/interactive-deps";
 import { parseCommand } from "@/lib/cli-parser";
 import { applyPendingHandoff, listProjectPendingHandoffs } from "@/lib/handoff";
 import { appendLog } from "@/lib/logger";
+import type { LogEntry } from "@/lib/types";
 
 interface ApplyOptions {
   session?: string;
 }
 
-type ApplyDeps = InteractiveCommandDeps;
+type ApplyDeps = InteractiveCommandDeps &
+  PromptDeps & {
+    cwd: () => string;
+    listProjectPendingHandoffs: typeof listProjectPendingHandoffs;
+    applyPendingHandoff: typeof applyPendingHandoff;
+    appendLog: (logPath: string, entry: LogEntry) => Promise<void>;
+  };
 
-const DEFAULT_APPLY_DEPS = createInteractiveCommandDeps();
+const DEFAULT_APPLY_DEPS: ApplyDeps = {
+  ...createInteractiveCommandDeps(),
+  ...createPromptDeps(),
+  cwd: () => process.cwd(),
+  listProjectPendingHandoffs,
+  applyPendingHandoff,
+  appendLog,
+};
 
 const NO_PENDING_HANDOFFS_MESSAGE = "No pending review handoffs for current working directory.";
 
@@ -37,10 +52,10 @@ export async function runApply(args: string[], deps: Partial<ApplyDeps> = {}): P
     return;
   }
 
-  const projectPath = process.cwd();
-  const handoffs = await listProjectPendingHandoffs(undefined, projectPath);
+  const projectPath = applyDeps.cwd();
+  const handoffs = await applyDeps.listProjectPendingHandoffs(undefined, projectPath);
   if (handoffs.length === 0) {
-    p.log.info(NO_PENDING_HANDOFFS_MESSAGE);
+    applyDeps.logInfo(NO_PENDING_HANDOFFS_MESSAGE);
     return;
   }
 
@@ -49,6 +64,8 @@ export async function runApply(args: string[], deps: Partial<ApplyDeps> = {}): P
     selector: parsed.session,
     action: "apply",
     isTTY: applyDeps.isTTY(),
+    select: applyDeps.select,
+    isCancel: applyDeps.isCancel,
   });
 
   if (!selection.handoff) {
@@ -59,21 +76,27 @@ export async function runApply(args: string[], deps: Partial<ApplyDeps> = {}): P
     return;
   }
 
-  p.log.step(`Applying handoff: ${selection.handoff.handoffId}`);
+  applyDeps.logStep(`Applying handoff: ${selection.handoff.handoffId}`);
 
   try {
-    const artifact = await applyPendingHandoff(undefined, projectPath, selection.handoff.handoffId);
-    await appendLog(artifact.logPath, {
+    const artifact = await applyDeps.applyPendingHandoff(
+      undefined,
+      projectPath,
+      selection.handoff.handoffId
+    );
+    await applyDeps.appendLog(artifact.logPath, {
       type: "handoff",
       timestamp: Date.now(),
       handoffId: artifact.handoffId,
       handoffStatus: "applied-manual",
       commitSha: artifact.commitSha,
     });
-    p.log.success("Review handoff applied.");
+    applyDeps.logSuccess("Review handoff applied.");
   } catch (error) {
     applyDeps.logError(`${error}`);
     applyDeps.exit(1);
     return;
   }
 }
+
+export type { ApplyDeps };

package/src/commands/interactive-deps.ts

@@ -8,6 +8,20 @@ export interface InteractiveCommandDeps {
   isTTY: () => boolean;
 }
 
+export type PromptSelect = (input: {
+  message: string;
+  options: Array<{ value: string; label: string; hint: string }>;
+}) => Promise<unknown>;
+
+export interface PromptDeps {
+  logInfo: (message: string) => void;
+  logMessage: (message: string) => void;
+  logStep: (message: string) => void;
+  logSuccess: (message: string) => void;
+  select: PromptSelect;
+  isCancel: (value: unknown) => boolean;
+}
+
 export function createInteractiveCommandDeps(): InteractiveCommandDeps {
   return {
     getCommandDef,
@@ -16,3 +30,14 @@ export function createInteractiveCommandDeps(): InteractiveCommandDeps {
     isTTY: () => process.stdout.isTTY === true,
   };
 }
+
+export function createPromptDeps(): PromptDeps {
+  return {
+    logInfo: p.log.info,
+    logMessage: p.log.message,
+    logStep: p.log.step,
+    logSuccess: p.log.success,
+    select: p.select,
+    isCancel: p.isCancel,
+  };
+}

package/src/commands/list.ts

@@ -2,6 +2,20 @@ import * as p from "@clack/prompts";
 import { listAllActiveSessions } from "@/lib/session-state";
 import { listRalphSessions } from "@/lib/tmux";
 
+interface ListDeps {
+  listAllActiveSessions: typeof listAllActiveSessions;
+  listRalphSessions: typeof listRalphSessions;
+  logInfo: (message: string) => void;
+  print: (...args: unknown[]) => void;
+}
+
+const DEFAULT_LIST_DEPS: ListDeps = {
+  listAllActiveSessions,
+  listRalphSessions,
+  logInfo: p.log.info,
+  print: (...args) => console.log(...args),
+};
+
 function formatRelativeStart(startTime: number): string {
   const elapsedSeconds = Math.max(0, Math.floor((Date.now() - startTime) / 1000));
 
@@ -18,10 +32,11 @@ function formatRelativeStart(startTime: number): string {
   return `${elapsedHours}h ago`;
 }
 
-export async function runList(): Promise<void> {
+export async function runList(deps: Partial<ListDeps> = {}): Promise<void> {
+  const listDeps = { ...DEFAULT_LIST_DEPS, ...deps };
   const [activeSessions, tmuxSessions] = await Promise.all([
-    listAllActiveSessions(),
-    listRalphSessions(),
+    listDeps.listAllActiveSessions(),
+    listDeps.listRalphSessions(),
   ]);
   const trackedTmuxSessions = new Set(activeSessions.map((session) => session.sessionName));
   const untrackedTmuxSessions = tmuxSessions.filter(
@@ -29,17 +44,19 @@ export async function runList(): Promise<void> {
   );
 
   if (activeSessions.length === 0 && untrackedTmuxSessions.length === 0) {
-    p.log.info("No active review sessions.");
+    listDeps.logInfo("No active review sessions.");
   } else {
-    p.log.info("Active review sessions:");
+    listDeps.logInfo("Active review sessions:");
     for (const session of activeSessions) {
       const worktree = session.worktreeBranch ? ` ${session.worktreeBranch}` : "";
-      console.log(
+      listDeps.print(
         `${session.sessionId.slice(0, 8)} ${session.sessionName} ${session.projectPath}${worktree} ${formatRelativeStart(session.startTime)}`
       );
     }
     for (const sessionName of untrackedTmuxSessions) {
-      console.log(`${sessionName} (tmux only)`);
+      listDeps.print(`${sessionName} (tmux only)`);
     }
   }
 }
+
+export type { ListDeps };

package/src/commands/status.ts

@@ -1,13 +1,34 @@
 import { getGitBranch } from "@/lib/logger";
 
-export async function runStatus(): Promise<void> {
-  const projectPath = process.cwd();
-  const branch = await getGitBranch(projectPath);
+interface StatusDeps {
+  cwd: () => string;
+  getGitBranch: typeof getGitBranch;
+  renderDashboard: (payload: { projectPath: string; branch: string | undefined }) => Promise<void>;
+}
 
+async function renderDashboardWithDynamicImport(payload: {
+  projectPath: string;
+  branch: string | undefined;
+}): Promise<void> {
   const { renderDashboard } = await import("@/lib/tui/index");
+  await renderDashboard(payload);
+}
+
+const DEFAULT_STATUS_DEPS: StatusDeps = {
+  cwd: () => process.cwd(),
+  getGitBranch,
+  renderDashboard: renderDashboardWithDynamicImport,
+};
 
-  await renderDashboard({
+export async function runStatus(deps: Partial<StatusDeps> = {}): Promise<void> {
+  const statusDeps = { ...DEFAULT_STATUS_DEPS, ...deps };
+  const projectPath = statusDeps.cwd();
+  const branch = await statusDeps.getGitBranch(projectPath);
+
+  await statusDeps.renderDashboard({
     projectPath,
     branch,
   });
 }
+
+export type { StatusDeps };

package/src/commands/stop.ts

@@ -1,7 +1,8 @@
-import * as p from "@clack/prompts";
 import {
   createInteractiveCommandDeps,
+  createPromptDeps,
   type InteractiveCommandDeps,
+  type PromptDeps,
 } from "@/commands/interactive-deps";
 import { parseCommand } from "@/lib/cli-parser";
 import { listProjectPendingHandoffs } from "@/lib/handoff";
@@ -25,9 +26,47 @@ interface StopOptions {
   session?: string;
 }
 
-type StopDeps = InteractiveCommandDeps;
+type StopDeps = InteractiveCommandDeps &
+  PromptDeps & {
+    cwd: () => string;
+    computeSessionStats: typeof computeSessionStats;
+    listProjectPendingHandoffs: typeof listProjectPendingHandoffs;
+    listAllActiveSessions: typeof listAllActiveSessions;
+    listProjectActiveSessions: typeof listProjectActiveSessions;
+    removeAllSessionStates: typeof removeAllSessionStates;
+    stopActiveSession: typeof stopActiveSession;
+    updateSessionState: typeof updateSessionState;
+    sendInterrupt: typeof sendInterrupt;
+    readSessionState: typeof readSessionState;
+    sessionExists: typeof sessionExists;
+    killSession: typeof killSession;
+    removeSessionState: typeof removeSessionState;
+    listRalphSessions: typeof listRalphSessions;
+    sleep: (ms: number) => Promise<void>;
+  };
 
-const DEFAULT_STOP_DEPS = createInteractiveCommandDeps();
+const DEFAULT_STOP_DEPS: StopDeps = {
+  ...createInteractiveCommandDeps(),
+  ...createPromptDeps(),
+  cwd: () => process.cwd(),
+  computeSessionStats,
+  listProjectPendingHandoffs,
+  listAllActiveSessions,
+  listProjectActiveSessions,
+  removeAllSessionStates,
+  stopActiveSession,
+  updateSessionState,
+  sendInterrupt,
+  readSessionState,
+  sessionExists,
+  killSession,
+  removeSessionState,
+  listRalphSessions,
+  sleep: (ms) =>
+    new Promise<void>((resolve) => {
+      setTimeout(resolve, ms);
+    }),
+};
 
 type ResolvedStopHandoff = {
   handoffStatus: Extract<HandoffStatus, "applied-auto" | "pending-apply" | "apply-conflicted">;
@@ -90,12 +129,13 @@ function createLogSessionFromPath(session: ActiveSession): LogSession | null {
 }
 
 async function resolveStoppedSessionHandoff(
-  session: ActiveSession
+  session: ActiveSession,
+  deps: StopDeps
 ): Promise<ResolvedStopHandoff | null> {
   const logSession = createLogSessionFromPath(session);
   if (logSession) {
     try {
-      const stats = await computeSessionStats(logSession);
+      const stats = await deps.computeSessionStats(logSession);
       if (
         (!stats.sessionId || stats.sessionId === session.sessionId) &&
         isReportedStopHandoffStatus(stats.handoffStatus)
@@ -112,7 +152,7 @@ async function resolveStoppedSessionHandoff(
   }
 
   try {
-    const pendingHandoffs = await listProjectPendingHandoffs(undefined, session.projectPath);
+    const pendingHandoffs = await deps.listProjectPendingHandoffs(undefined, session.projectPath);
     const matchingHandoffs = pendingHandoffs.filter(
       (handoff) => handoff.sessionId === session.sessionId
     );
@@ -153,9 +193,10 @@ function formatProjectScopedCommand(
 
 async function resolveStoppedSessionHandoffNote(
   session: ActiveSession,
-  currentProjectPath: string
+  currentProjectPath: string,
+  deps: StopDeps
 ): Promise<string | null> {
-  const handoff = await resolveStoppedSessionHandoff(session);
+  const handoff = await resolveStoppedSessionHandoff(session, deps);
   if (!handoff) {
     return null;
   }
@@ -181,18 +222,20 @@ async function resolveStoppedSessionHandoffNote(
 
 async function stopSessionWithHandoff(
   session: ActiveSession,
-  currentProjectPath: string
+  currentProjectPath: string,
+  deps: StopDeps
 ): Promise<string | null> {
-  await stopActiveSession(session, {
-    updateSessionState,
-    sendInterrupt,
-    readSessionState,
-    sessionExists,
-    killSession,
-    removeSessionState,
+  await deps.stopActiveSession(session, {
+    updateSessionState: deps.updateSessionState,
+    sendInterrupt: deps.sendInterrupt,
+    readSessionState: deps.readSessionState,
+    sessionExists: deps.sessionExists,
+    killSession: deps.killSession,
+    removeSessionState: deps.removeSessionState,
+    sleep: deps.sleep,
   });
 
-  return await resolveStoppedSessionHandoffNote(session, currentProjectPath);
+  return await resolveStoppedSessionHandoffNote(session, currentProjectPath, deps);
 }
 
 function findSessionBySelector(
@@ -233,9 +276,10 @@ function findSessionBySelector(
 }
 
 async function chooseProjectSession(
-  projectSessions: ActiveSession[]
+  projectSessions: ActiveSession[],
+  deps: StopDeps
 ): Promise<ActiveSession | null> {
-  const selection = await p.select({
+  const selection = await deps.select({
     message: "Choose a review session to stop",
     options: projectSessions.map((session) => ({
       value: session.sessionId,
@@ -244,38 +288,38 @@ async function chooseProjectSession(
     })),
   });
 
-  if (p.isCancel(selection)) {
+  if (deps.isCancel(selection)) {
     return null;
   }
 
   return projectSessions.find((session) => session.sessionId === selection) ?? null;
 }
 
-async function stopSession(session: ActiveSession): Promise<void> {
-  p.log.step(`Stopping session: ${session.sessionName}`);
-  const handoffNote = await stopSessionWithHandoff(session, process.cwd());
-  p.log.success("Review stopped.");
+async function stopSession(session: ActiveSession, deps: StopDeps): Promise<void> {
+  deps.logStep(`Stopping session: ${session.sessionName}`);
+  const handoffNote = await stopSessionWithHandoff(session, deps.cwd(), deps);
+  deps.logSuccess("Review stopped.");
   if (handoffNote) {
-    p.log.message(`Handoff:\n${handoffNote}`);
+    deps.logMessage(`Handoff:\n${handoffNote}`);
   }
 }
 
-async function stopAllSessions(): Promise<void> {
+async function stopAllSessions(deps: StopDeps): Promise<void> {
   const orphanStopGracePeriod = 1_000;
-  const currentProjectPath = process.cwd();
-  const activeSessions = await listAllActiveSessions();
-  const tmuxSessions = await listRalphSessions();
+  const currentProjectPath = deps.cwd();
+  const activeSessions = await deps.listAllActiveSessions();
+  const tmuxSessions = await deps.listRalphSessions();
   const sessionNames = [
     ...new Set([...tmuxSessions, ...activeSessions.map((session) => session.sessionName)]),
   ];
 
   if (sessionNames.length === 0) {
-    p.log.info("No active review sessions.");
-    await removeAllSessionStates();
+    deps.logInfo("No active review sessions.");
+    await deps.removeAllSessionStates();
     return;
   }
 
-  p.log.step(`Stopping ${sessionNames.length} session(s)...`);
+  deps.logStep(`Stopping ${sessionNames.length} session(s)...`);
 
   const activeSessionsByName = new Map(
     activeSessions.map((session) => [session.sessionName, session] as const)
@@ -285,38 +329,36 @@ async function stopAllSessions(): Promise<void> {
   );
   const activeStopPromise = Promise.all(
     activeSessions.map(async (session) => ({
-      handoffNote: await stopSessionWithHandoff(session, currentProjectPath),
+      handoffNote: await stopSessionWithHandoff(session, currentProjectPath, deps),
     }))
   );
 
   for (const sessionName of orphanSessionNames) {
-    await sendInterrupt(sessionName);
+    await deps.sendInterrupt(sessionName);
   }
 
   const stoppedActiveSessions = await activeStopPromise;
 
   if (orphanSessionNames.length > 0) {
-    await new Promise<void>((resolve) => {
-      setTimeout(resolve, orphanStopGracePeriod);
-    });
+    await deps.sleep(orphanStopGracePeriod);
   }
 
   for (const sessionName of orphanSessionNames) {
-    await killSession(sessionName);
+    await deps.killSession(sessionName);
   }
 
   for (const sessionName of sessionNames) {
-    p.log.message(`  Stopped: ${sessionName}`);
+    deps.logMessage(`  Stopped: ${sessionName}`);
   }
 
   for (const stoppedSession of stoppedActiveSessions) {
     if (stoppedSession.handoffNote) {
-      p.log.message(`Handoff:\n${stoppedSession.handoffNote}`);
+      deps.logMessage(`Handoff:\n${stoppedSession.handoffNote}`);
     }
   }
 
-  await removeAllSessionStates();
-  p.log.success(`Stopped ${sessionNames.length} session(s).`);
+  await deps.removeAllSessionStates();
+  deps.logSuccess(`Stopped ${sessionNames.length} session(s).`);
 }
 
 async function stopCurrentProjectSession(
@@ -325,7 +367,7 @@ async function stopCurrentProjectSession(
   deps: StopDeps
 ): Promise<void> {
   const projectSessions = getCurrentProjectSessions(
-    await listProjectActiveSessions(undefined, projectPath),
+    await deps.listProjectActiveSessions(undefined, projectPath),
     projectPath
   );
 
@@ -337,17 +379,17 @@ async function stopCurrentProjectSession(
       return;
     }
 
-    await stopSession(match.session);
+    await stopSession(match.session, deps);
     return;
   }
 
   if (projectSessions.length === 0) {
-    p.log.info("No active review session for current working directory.");
+    deps.logInfo("No active review session for current working directory.");
 
-    const allSessions = await listAllActiveSessions();
+    const allSessions = await deps.listAllActiveSessions();
     if (allSessions.length > 0) {
-      p.log.message(`\nThere are ${allSessions.length} other session(s) running.`);
-      p.log.message(
+      deps.logMessage(`\nThere are ${allSessions.length} other session(s) running.`);
+      deps.logMessage(
         'Use "rr stop --all" to stop all running review sessions, or "rr" to see details.'
       );
     }
@@ -357,7 +399,7 @@ async function stopCurrentProjectSession(
   if (projectSessions.length === 1) {
     const onlySession = projectSessions[0];
     if (onlySession) {
-      await stopSession(onlySession);
+      await stopSession(onlySession, deps);
     }
     return;
   }
@@ -370,12 +412,12 @@ async function stopCurrentProjectSession(
     return;
   }
 
-  const selectedSession = await chooseProjectSession(projectSessions);
+  const selectedSession = await chooseProjectSession(projectSessions, deps);
   if (!selectedSession) {
     return;
   }
 
-  await stopSession(selectedSession);
+  await stopSession(selectedSession, deps);
 }
 
 export async function runStop(args: string[], deps: Partial<StopDeps> = {}): Promise<void> {
@@ -399,9 +441,11 @@ export async function runStop(args: string[], deps: Partial<StopDeps> = {}): Pro
   }
 
   if (options.all) {
-    await stopAllSessions();
+    await stopAllSessions(stopDeps);
     return;
   }
 
-  await stopCurrentProjectSession(process.cwd(), options.session, stopDeps);
+  await stopCurrentProjectSession(stopDeps.cwd(), options.session, stopDeps);
 }
+
+export type { StopDeps };

package/src/lib/agents/models.ts

@@ -52,6 +52,15 @@ export function registerDroidReasoningOptions(
   }
 }
 
+export function resetRegisteredReasoningOptions(): void {
+  Object.keys(codexReasoningLevelsByModel).forEach((model) => {
+    delete codexReasoningLevelsByModel[model];
+  });
+  Object.keys(droidReasoningLevelsByModel).forEach((model) => {
+    delete droidReasoningLevelsByModel[model];
+  });
+}
+
 export function getDroidReasoningOptions(model: string): ReasoningLevel[] {
   const levels = droidReasoningLevelsByModel[model];
   return levels ? [...levels] : [];

package/src/lib/review-workflow/review/run-review-session.ts

@@ -325,6 +325,20 @@ export async function runReviewSession(
     if (entry.type === "review_iteration") {
       latestPersistedFindings = [...latestPersistedFindings, ...entry.findings];
       completedReviewIterations = entry.iteration;
+
+      if (worktree && latestPersistedFindings.length > 0) {
+        await deps.saveFindingsArtifact(
+          CONFIG_DIR,
+          createFindingsArtifact(
+            sessionId,
+            projectPath,
+            sessionPath,
+            worktree,
+            latestPersistedFindings
+          )
+        );
+        shouldDeleteSessionRefs = false;
+      }
     }
   };
 

package/src/lib/stop-session.ts

@@ -1,5 +1,5 @@
 import { discardSessionWorktree, type GitSessionWorktree } from "@/lib/git";
-import { deleteSessionFiles, readLog } from "@/lib/logger";
+import { appendLog, deleteSessionFiles, readLog } from "@/lib/logger";
 import {
   type ActiveSession,
   readSessionState,
@@ -27,6 +27,7 @@ interface WaitForGracefulStopDeps {
 
 interface StopActiveSessionDeps {
   readLog: typeof readLog;
+  appendLog: typeof appendLog;
   deleteSessionFiles: typeof deleteSessionFiles;
   updateSessionState: typeof updateSessionState;
   sendInterrupt: typeof sendInterrupt;
@@ -41,6 +42,7 @@ interface StopActiveSessionDeps {
 
 const DEFAULT_STOP_ACTIVE_SESSION_DEPS: StopActiveSessionDeps = {
   readLog,
+  appendLog,
   deleteSessionFiles,
   updateSessionState,
   sendInterrupt,
@@ -137,6 +139,7 @@ interface SessionIterationState {
   hasRecordedIteration: boolean;
   hasRecordedReviewProgress: boolean;
   hasSuccessfulReviewIteration: boolean;
+  entries: LogEntry[];
 }
 
 async function resolveSessionIterationState(
@@ -153,12 +156,58 @@ async function resolveSessionIterationState(
       hasRecordedIteration: hasRecordedIteration(entries),
       hasRecordedReviewProgress: hasRecordedReviewProgress(entries),
       hasSuccessfulReviewIteration: hasSuccessfulReviewIteration(entries),
+      entries,
     };
   } catch {
     return null;
   }
 }
 
+function getLatestLifecycleEntry(entries: LogEntry[]): LogEntry | undefined {
+  return [...entries].reverse().find((entry) => entry.type !== "handoff");
+}
+
+function getLatestReviewIteration(entries: LogEntry[]) {
+  return entries.filter((entry) => entry.type === "review_iteration").at(-1);
+}
+
+function getAccumulatedReviewFindings(entries: LogEntry[]) {
+  return entries.flatMap((entry) => (entry.type === "review_iteration" ? entry.findings : []));
+}
+
+async function terminalizeForceStoppedReviewSession(
+  session: ActiveSession,
+  iterationState: SessionIterationState | null,
+  deps: StopActiveSessionDeps
+): Promise<void> {
+  if (!session.sessionPath || !iterationState?.hasRecordedReviewProgress) {
+    return;
+  }
+
+  if (getLatestLifecycleEntry(iterationState.entries)?.type === "session_end") {
+    return;
+  }
+
+  const latestReviewIteration = getLatestReviewIteration(iterationState.entries);
+  if (!latestReviewIteration) {
+    return;
+  }
+
+  await deps.appendLog(session.sessionPath, {
+    type: "session_end",
+    timestamp: Date.now(),
+    status: "interrupted",
+    reason: "Review stopped by user.",
+    iterations: latestReviewIteration.iteration,
+    phase: "review",
+    sessionStatus: "interrupted",
+    reviewOutcome:
+      getAccumulatedReviewFindings(iterationState.entries).length > 0
+        ? "findings-pending"
+        : "incomplete",
+  });
+}
+
 function createCleanupWorktree(
   session: ActiveSession,
   sourceRepoPath: string
@@ -239,6 +288,15 @@ export async function stopActiveSession(
   }
 
   const finalIterationState = await resolveSessionIterationState(session, stopDeps);
+  let terminalizeSessionError: unknown;
+  if (!stoppedGracefully) {
+    try {
+      await terminalizeForceStoppedReviewSession(session, finalIterationState, stopDeps);
+    } catch (error) {
+      terminalizeSessionError = error;
+    }
+  }
+
   if (finalIterationState?.hasSuccessfulReviewIteration === false) {
     cleanupUnpromotedSessionWorktree(session, stopDeps);
   }
@@ -256,6 +314,10 @@ export async function stopActiveSession(
     expectedSessionId: session.sessionId,
   });
 
+  if (terminalizeSessionError) {
+    throw terminalizeSessionError;
+  }
+
   if (deleteSessionFilesError) {
     throw deleteSessionFilesError;
   }

package/src/lib/tui/dashboard/Dashboard.tsx

@@ -17,9 +17,11 @@ import { StatusBar } from "./StatusBar";
 import { useDashboardRunControl } from "./use-dashboard-run-control";
 import { useDashboardStopControl } from "./use-dashboard-stop-control";
 
-export function Dashboard({ projectPath, branch, refreshInterval = 1000 }: DashboardProps) {
+export function Dashboard({ projectPath, branch, refreshInterval = 1000, deps }: DashboardProps) {
   const renderer = useRenderer();
-  const state = useWorkspaceState(projectPath, branch, refreshInterval);
+  const resolvedUseWorkspaceState = deps?.useWorkspaceState ?? useWorkspaceState;
+  const ResolvedDashboardOverlays = deps?.DashboardOverlays ?? DashboardOverlays;
+  const state = resolvedUseWorkspaceState(projectPath, branch, refreshInterval);
   const {
     runError,
     startupMode,
@@ -29,7 +31,7 @@ export function Dashboard({ projectPath, branch, refreshInterval = 1000 }: Dashb
     spawnRunProcess,
     spawnFixProcess,
     isStartupSpawning,
-  } = useDashboardRunControl(projectPath);
+  } = useDashboardRunControl(projectPath, { spawn: deps?.spawn });
   const [focusedPane, setFocusedPane] = useState<FocusedPane>("detail");
   const [outputVisible, setOutputVisible] = useState(false);
   const [showHelp, setShowHelp] = useState(false);
@@ -37,11 +39,14 @@ export function Dashboard({ projectPath, branch, refreshInterval = 1000 }: Dashb
   const [showSession, setShowSession] = useState(false);
   const [showReviewModeOverlay, setShowReviewModeOverlay] = useState(false);
   const [showStopPicker, setShowStopPicker] = useState(false);
-  const { isStoppingRun, stopSelectedSession } = useDashboardStopControl({
-    currentSession: state.currentSession,
-    setShowStopPicker,
-    onError: setRunError,
-  });
+  const { isStoppingRun, stopSelectedSession } = useDashboardStopControl(
+    {
+      currentSession: state.currentSession,
+      setShowStopPicker,
+      onError: setRunError,
+    },
+    { stopActiveSession: deps?.stopActiveSession }
+  );
 
   const projectName = basename(projectPath);
   const isExitingRef = useRef(false);
@@ -271,7 +276,7 @@ export function Dashboard({ projectPath, branch, refreshInterval = 1000 }: Dashb
           liveRefreshError={state.liveRefreshError}
           configWarning={state.configWarning}
         />
-        <DashboardOverlays
+        <ResolvedDashboardOverlays
           showHelp={showHelp}
           showRunOverlay={showRunOverlay}
           showFixFindings={showFixFindings}

package/src/lib/tui/dashboard/ReviewModeOverlay.tsx

@@ -1023,7 +1023,7 @@ export function ReviewModeOverlay({
               width={textareaWidth}
               height={isWideOptionsLayout ? 5 : 4}
               wrapMode="word"
-              keyBindings={[{ name: "return", shift: true, action: "submit" }]}
+              keyBindings={[{ name: "return", ctrl: true, action: "submit" }]}
               onSubmit={() => {
                 submitWithOptions();
               }}
@@ -1090,7 +1090,7 @@ export function ReviewModeOverlay({
   function renderOptions() {
     const isPriorityFocusActive = optionsFocus === "execution-auto-priority";
     const isForceControlActive = optionsFocus === "force-max-iterations";
-    const reviewStartKeyLabel = isCustomInstructionsFocused ? "[Shift+Enter]" : "[Enter]";
+    const reviewStartKeyLabel = isCustomInstructionsFocused ? "[Ctrl+Enter]" : "[Enter]";
 
     return (
       <box flexDirection="column" gap={0}>

package/src/lib/tui/dashboard/use-dashboard-run-control.ts

@@ -15,10 +15,18 @@ export interface DashboardRunControl {
   isStartupSpawning: () => boolean;
 }
 
-export function useDashboardRunControl(projectPath: string): DashboardRunControl {
+interface DashboardRunControlDeps {
+  spawn?: typeof Bun.spawn;
+}
+
+export function useDashboardRunControl(
+  projectPath: string,
+  deps?: DashboardRunControlDeps
+): DashboardRunControl {
   const [runError, setRunError] = useState<string | null>(null);
   const [startupMode, setStartupMode] = useState<DashboardStartupMode>(null);
   const isStartupSpawningRef = useRef(false);
+  const spawn = deps?.spawn ?? Bun.spawn;
 
   const clearRunError = useCallback(() => {
     setRunError(null);
@@ -40,7 +48,7 @@ export function useDashboardRunControl(projectPath: string): DashboardRunControl
       setStartupMode(nextStartupMode);
 
       try {
-        const subprocess = Bun.spawn([process.execPath, CLI_PATH, command, ...argv], {
+        const subprocess = spawn([process.execPath, CLI_PATH, command, ...argv], {
           cwd: projectPath,
           stdin: "ignore",
           stdout: "pipe",
@@ -73,7 +81,7 @@ export function useDashboardRunControl(projectPath: string): DashboardRunControl
         setRunError(getErrorMessage(error));
       }
     },
-    [projectPath]
+    [projectPath, spawn]
   );
 
   const spawnRunProcess = useCallback(

package/src/lib/tui/dashboard/use-dashboard-stop-control.ts

@@ -22,13 +22,17 @@ export interface DashboardStopControl {
   stopSelectedSession: (session: ActiveSession) => Promise<void>;
 }
 
-export function useDashboardStopControl({
-  currentSession,
-  setShowStopPicker,
-  onError,
-}: DashboardStopControlOptions): DashboardStopControl {
+interface DashboardStopControlDeps {
+  stopActiveSession?: typeof stopActiveSession;
+}
+
+export function useDashboardStopControl(
+  options: DashboardStopControlOptions,
+  deps?: DashboardStopControlDeps
+): DashboardStopControl {
   const [stoppingSession, setStoppingSession] = useState<StoppingSessionState | null>(null);
   const settleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const stopSession = deps?.stopActiveSession ?? stopActiveSession;
 
   const clearSettleTimer = useMemo(
     () => () => {
@@ -42,7 +46,10 @@ export function useDashboardStopControl({
 
   if (
     stoppingSession &&
-    shouldClearStoppingSessionState({ marker: stoppingSession, currentSession })
+    shouldClearStoppingSessionState({
+      marker: stoppingSession,
+      currentSession: options.currentSession,
+    })
   ) {
     clearSettleTimer();
     setStoppingSession(null);
@@ -57,8 +64,8 @@ export function useDashboardStopControl({
 
       try {
         await stopSelectedDashboardSession(session, {
-          setShowStopPicker,
-          stopActiveSession,
+          setShowStopPicker: options.setShowStopPicker,
+          stopActiveSession: stopSession,
         });
 
         const settled = settleStoppingSessionState(createStoppingSessionState(session));
@@ -78,10 +85,10 @@ export function useDashboardStopControl({
       } catch (error) {
         clearSettleTimer();
         setStoppingSession(null);
-        onError(getErrorMessage(error));
+        options.onError(getErrorMessage(error));
       }
     },
-    [clearSettleTimer, onError, setShowStopPicker]
+    [clearSettleTimer, options.onError, options.setShowStopPicker, stopSession]
   );
 
   return {

package/src/lib/tui/shared/types.ts

@@ -1,5 +1,15 @@
+import type { stopActiveSession } from "@/lib/stop-session";
+import type { DashboardOverlays } from "@/lib/tui/dashboard/DashboardOverlays";
+import type { useWorkspaceState } from "@/lib/tui/workspace/use-workspace-state";
+
 export interface DashboardProps {
   projectPath: string;
   branch?: string;
   refreshInterval?: number;
+  deps?: {
+    useWorkspaceState?: typeof useWorkspaceState;
+    DashboardOverlays?: typeof DashboardOverlays;
+    spawn?: typeof Bun.spawn;
+    stopActiveSession?: typeof stopActiveSession;
+  };
 }

package/src/lib/tui/workspace/use-workspace-state.ts

@@ -2,7 +2,7 @@ import { basename } from "node:path";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { loadEffectiveConfig } from "@/lib/config";
 import { ensureGitRepositoryAsync } from "@/lib/git";
-import type { LogIncrementalState } from "@/lib/logger";
+import type { LogIncrementalState, LogSession } from "@/lib/logger";
 import {
   computeProjectStats,
   computeSessionStats,
@@ -11,7 +11,7 @@ import {
   listProjectLogSessions,
   readLogIncremental,
 } from "@/lib/logger";
-import type { ActiveSession } from "@/lib/session-state";
+import type { ActiveSession, SessionState } from "@/lib/session-state";
 import {
   getLatestProjectActiveSession,
   listAllActiveSessions,
@@ -35,7 +35,48 @@ import {
 import type { SessionGroupData, WorkspaceState } from "./workspace-types";
 
 const DEFAULT_REFRESH_INTERVAL = 1000;
-const LIVE_REFRESH_INTERVAL = TMUX_CAPTURE_MIN_INTERVAL_MS;
+
+export interface WorkspaceStateDeps {
+  loadEffectiveConfig: typeof loadEffectiveConfig;
+  ensureGitRepositoryAsync: typeof ensureGitRepositoryAsync;
+  listAllActiveSessions: typeof listAllActiveSessions;
+  listProjectActiveSessions: typeof listProjectActiveSessions;
+  getLatestProjectActiveSession: (
+    storageRoot: string | undefined,
+    projectPath: string
+  ) => Promise<SessionState | null>;
+  getLatestProjectLogSession: (
+    storageRoot: string | undefined,
+    projectPath: string
+  ) => Promise<LogSession | null>;
+  readLogIncremental: typeof readLogIncremental;
+  listProjectLogSessions: typeof listProjectLogSessions;
+  computeSessionStats: typeof computeSessionStats;
+  computeProjectStats: typeof computeProjectStats;
+  getProjectName: typeof getProjectName;
+  shouldCaptureTmux: typeof shouldCaptureTmux;
+  getSessionOutput: (sessionName: string, lines: number) => Promise<string>;
+  computeNextTmuxCaptureInterval: typeof computeNextTmuxCaptureInterval;
+  tmuxCaptureMinIntervalMs: number;
+}
+
+const defaultWorkspaceStateDeps: WorkspaceStateDeps = {
+  loadEffectiveConfig,
+  ensureGitRepositoryAsync,
+  listAllActiveSessions,
+  listProjectActiveSessions,
+  getLatestProjectActiveSession,
+  getLatestProjectLogSession,
+  readLogIncremental,
+  listProjectLogSessions,
+  computeSessionStats,
+  computeProjectStats,
+  getProjectName,
+  shouldCaptureTmux,
+  getSessionOutput,
+  computeNextTmuxCaptureInterval,
+  tmuxCaptureMinIntervalMs: TMUX_CAPTURE_MIN_INTERVAL_MS,
+};
 
 export function createInitialWorkspaceState(
   overrides: Partial<WorkspaceState> = {}
@@ -121,7 +162,8 @@ function buildSessionGroups(
 export function useWorkspaceState(
   projectPath: string,
   _branch?: string,
-  refreshInterval: number = DEFAULT_REFRESH_INTERVAL
+  refreshInterval: number = DEFAULT_REFRESH_INTERVAL,
+  deps: WorkspaceStateDeps = defaultWorkspaceStateDeps
 ): WorkspaceState {
   const [state, setState] = useState<WorkspaceState>(() => createInitialWorkspaceState());
 
@@ -133,7 +175,7 @@ export function useWorkspaceState(
   const lastTmuxCaptureRef = useRef(0);
   const lastTmuxOutputRef = useRef("");
   const lastTmuxSessionRef = useRef<string | null>(null);
-  const tmuxCaptureIntervalRef = useRef(TMUX_CAPTURE_MIN_INTERVAL_MS);
+  const tmuxCaptureIntervalRef = useRef(deps.tmuxCaptureMinIntervalMs);
   const lastLiveMetaRef = useRef<LiveRefreshMeta | null>(null);
   const logIncrementalStateRef = useRef<LogIncrementalState | undefined>(undefined);
   const lastLogSessionPathRef = useRef<string | null>(null);
@@ -145,12 +187,12 @@ export function useWorkspaceState(
     try {
       const [isGitRepo, allSessions, projectSessions, currentSession, logSession, configResult] =
         await Promise.all([
-          ensureGitRepositoryAsync(projectPath),
-          listAllActiveSessions(),
-          listProjectActiveSessions(undefined, projectPath),
-          getLatestProjectActiveSession(undefined, projectPath),
-          getLatestProjectLogSession(undefined, projectPath),
-          loadWorkspaceConfigSafe(projectPath, loadEffectiveConfig),
+          deps.ensureGitRepositoryAsync(projectPath),
+          deps.listAllActiveSessions(),
+          deps.listProjectActiveSessions(undefined, projectPath),
+          deps.getLatestProjectActiveSession(undefined, projectPath),
+          deps.getLatestProjectLogSession(undefined, projectPath),
+          loadWorkspaceConfigSafe(projectPath, deps.loadEffectiveConfig),
         ]);
 
       const sessionGroups = buildSessionGroups(allSessions, projectPath);
@@ -172,7 +214,7 @@ export function useWorkspaceState(
 
       if (logPath) {
         const logSessionChanged = logPath !== lastLogSessionPathRef.current;
-        const incrementalResult = await readLogIncremental(
+        const incrementalResult = await deps.readLogIncremental(
           logPath,
           logSessionChanged ? undefined : logIncrementalStateRef.current
         );
@@ -209,11 +251,14 @@ export function useWorkspaceState(
       let projectStats: ProjectStats | null = null;
 
       if (!currentSession) {
-        const projectLogSessions = await listProjectLogSessions(undefined, projectPath);
+        const projectLogSessions = await deps.listProjectLogSessions(undefined, projectPath);
         const latestSession = projectLogSessions[0];
         if (latestSession) {
-          lastSessionStats = await computeSessionStats(latestSession);
-          projectStats = await computeProjectStats(getProjectName(projectPath), projectLogSessions);
+          lastSessionStats = await deps.computeSessionStats(latestSession);
+          projectStats = await deps.computeProjectStats(
+            deps.getProjectName(projectPath),
+            projectLogSessions
+          );
         }
       }
 
@@ -261,14 +306,14 @@ export function useWorkspaceState(
     } finally {
       isHeavyRefreshingRef.current = false;
     }
-  }, [projectPath]);
+  }, [deps, projectPath]);
 
   const refreshLive = useCallback(async () => {
     if (isLiveRefreshingRef.current) return;
     isLiveRefreshingRef.current = true;
 
     try {
-      const currentSession = await getLatestProjectActiveSession(undefined, projectPath);
+      const currentSession = await deps.getLatestProjectActiveSession(undefined, projectPath);
 
       let tmuxOutput = lastTmuxOutputRef.current;
       const liveMeta = getLiveRefreshMeta(currentSession);
@@ -281,10 +326,10 @@ export function useWorkspaceState(
         lastTmuxOutputRef.current = "";
         lastTmuxSessionRef.current = null;
         lastTmuxCaptureRef.current = 0;
-        tmuxCaptureIntervalRef.current = TMUX_CAPTURE_MIN_INTERVAL_MS;
+        tmuxCaptureIntervalRef.current = deps.tmuxCaptureMinIntervalMs;
       } else {
         const sessionChanged = sessionName !== lastTmuxSessionRef.current;
-        const shouldCapture = shouldCaptureTmux({
+        const shouldCapture = deps.shouldCaptureTmux({
           sessionChanged,
           liveMetaChanged,
           now,
@@ -293,14 +338,14 @@ export function useWorkspaceState(
         });
 
         if (shouldCapture) {
-          const capturedOutput = await getSessionOutput(sessionName, 1000);
+          const capturedOutput = await deps.getSessionOutput(sessionName, 1000);
           const nextOutput = capturedOutput || (sessionChanged ? "" : lastTmuxOutputRef.current);
           const outputChanged = nextOutput !== lastTmuxOutputRef.current;
           tmuxOutput = nextOutput;
           lastTmuxOutputRef.current = tmuxOutput;
           lastTmuxSessionRef.current = sessionName;
           lastTmuxCaptureRef.current = now;
-          tmuxCaptureIntervalRef.current = computeNextTmuxCaptureInterval({
+          tmuxCaptureIntervalRef.current = deps.computeNextTmuxCaptureInterval({
             sessionChanged,
             liveMetaChanged,
             outputChanged,
@@ -329,7 +374,7 @@ export function useWorkspaceState(
     } finally {
       isLiveRefreshingRef.current = false;
     }
-  }, [projectPath]);
+  }, [deps, projectPath]);
 
   useEffect(() => {
     void refreshHeavy();
@@ -345,9 +390,9 @@ export function useWorkspaceState(
   }, [refreshLive]);
 
   useEffect(() => {
-    const interval = setInterval(refreshLive, LIVE_REFRESH_INTERVAL);
+    const interval = setInterval(refreshLive, deps.tmuxCaptureMinIntervalMs);
     return () => clearInterval(interval);
-  }, [refreshLive]);
+  }, [deps.tmuxCaptureMinIntervalMs, refreshLive]);
 
   return state;
 }