ralph-review 0.2.2 → 0.2.3

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

@@ -56,7 +56,9 @@ export interface RunFixSessionDependencies {
   discardSessionWorktree: typeof discardSessionWorktree;
 }
 
-async function defaultPromptForSelection(artifact: FindingsArtifact): Promise<FindingId[] | null> {
+export async function promptForFixSelection(
+  artifact: FindingsArtifact
+): Promise<FindingId[] | null> {
   const selection = await p.multiselect({
     message: "Choose findings to fix",
     options: artifact.findings.map((finding) => ({
@@ -80,7 +82,7 @@ const DEFAULT_RUN_FIX_SESSION_DEPENDENCIES: RunFixSessionDependencies = {
   createSessionWorktreeAt,
   updateSelection,
   appendLog,
-  promptForSelection: defaultPromptForSelection,
+  promptForSelection: promptForFixSelection,
   runBatchFixPhase,
   appendFixResults,
   updateRetainedWorktree,
@@ -123,6 +125,26 @@ function buildRetainedCleanupWorktree(
   };
 }
 
+async function discardRetainedWorktree(
+  deps: RunFixSessionDependencies,
+  artifact: FindingsArtifact,
+  worktree: GitSessionWorktree,
+  retainedWorktree: RetainedSessionWorktree
+): Promise<FindingsArtifact> {
+  deps.discardSessionWorktree(buildRetainedCleanupWorktree(worktree, retainedWorktree));
+  try {
+    await deps.updateRetainedWorktree(
+      CONFIG_DIR,
+      artifact.projectPath,
+      artifact.sessionId,
+      undefined
+    );
+  } catch {
+    // Best-effort cleanup; the remediation result is still returned.
+  }
+  return artifact;
+}
+
 function resolveSelectionMode(selector: FixSessionSelector | undefined): {
   mode: "all" | "priority" | "id" | "interactive";
   count: number;
@@ -232,6 +254,26 @@ async function emitProgress(
   await onProgress?.(updates);
 }
 
+async function emitResultProgress(
+  onProgress: RunFixSessionOptions["onProgress"],
+  result: FixSessionResult,
+  updates: Partial<SessionState> = {}
+): Promise<void> {
+  await emitProgress(onProgress, {
+    currentPhase: result.phase,
+    phase: result.phase,
+    sessionStatus: result.sessionStatus,
+    currentAgent: null,
+    selectedFindingIds: result.selection.selectedFindingIds,
+    reviewOutcome: result.reviewOutcome,
+    handoffStatus: result.handoffStatus,
+    handoffId: result.handoffId,
+    handoffUpdatedAt: result.handoffUpdatedAt,
+    commitSha: result.commitSha,
+    ...updates,
+  });
+}
+
 export async function runFixSession(
   config: Config,
   options: RunFixSessionOptions,
@@ -263,18 +305,7 @@ export async function runFixSession(
         unselectedFindings: [...artifact.findings],
         reason: resolvedSelection.error,
       });
-      await emitProgress(options.onProgress, {
-        currentPhase: result.phase,
-        phase: result.phase,
-        sessionStatus: result.sessionStatus,
-        currentAgent: null,
-        selectedFindingIds: result.selection.selectedFindingIds,
-        reviewOutcome: result.reviewOutcome,
-        handoffStatus: result.handoffStatus,
-        handoffId: result.handoffId,
-        handoffUpdatedAt: result.handoffUpdatedAt,
-        commitSha: result.commitSha,
-      });
+      await emitResultProgress(options.onProgress, result);
       return result;
     }
 
@@ -287,18 +318,7 @@ export async function runFixSession(
         reason: "Selection cancelled. Findings remain pending.",
         unselectedFindings: [...artifact.findings],
       });
-      await emitProgress(options.onProgress, {
-        currentPhase: result.phase,
-        phase: result.phase,
-        sessionStatus: result.sessionStatus,
-        currentAgent: null,
-        selectedFindingIds: result.selection.selectedFindingIds,
-        reviewOutcome: result.reviewOutcome,
-        handoffStatus: result.handoffStatus,
-        handoffId: result.handoffId,
-        handoffUpdatedAt: result.handoffUpdatedAt,
-        commitSha: result.commitSha,
-      });
+      await emitResultProgress(options.onProgress, result);
       return result;
     }
 
@@ -334,18 +354,7 @@ export async function runFixSession(
         selection: resolvedSelection.selection,
         unselectedFindings: [...artifact.findings],
       });
-      await emitProgress(options.onProgress, {
-        currentPhase: result.phase,
-        phase: result.phase,
-        sessionStatus: result.sessionStatus,
-        currentAgent: null,
-        selectedFindingIds: result.selection.selectedFindingIds,
-        reviewOutcome: result.reviewOutcome,
-        handoffStatus: result.handoffStatus,
-        handoffId: result.handoffId,
-        handoffUpdatedAt: result.handoffUpdatedAt,
-        commitSha: result.commitSha,
-      });
+      await emitResultProgress(options.onProgress, result);
       return result;
     }
 
@@ -412,7 +421,21 @@ export async function runFixSession(
       worktree,
     });
 
-    if (result.reviewOutcome === "incomplete") {
+    if (result.handoffStatus) {
+      if (artifactWithFixResults.retainedWorktree) {
+        const artifactWithoutRetainedWorktree = await discardRetainedWorktree(
+          deps,
+          artifact,
+          worktree,
+          artifactWithFixResults.retainedWorktree
+        );
+        artifactForResult = artifactWithoutRetainedWorktree;
+        result = {
+          ...result,
+          artifact: artifactWithoutRetainedWorktree,
+        };
+      }
+    } else if (result.reviewOutcome === "incomplete") {
       try {
         retainedWorktree = deps.finalizeSessionWorktree(worktree) ?? undefined;
       } catch {
@@ -435,14 +458,11 @@ export async function runFixSession(
         };
       }
     } else if (artifactWithFixResults.retainedWorktree) {
-      deps.discardSessionWorktree(
-        buildRetainedCleanupWorktree(worktree, artifactWithFixResults.retainedWorktree)
-      );
-      const artifactWithoutRetainedWorktree = await deps.updateRetainedWorktree(
-        CONFIG_DIR,
-        artifact.projectPath,
-        artifact.sessionId,
-        undefined
+      const artifactWithoutRetainedWorktree = await discardRetainedWorktree(
+        deps,
+        artifact,
+        worktree,
+        artifactWithFixResults.retainedWorktree
       );
       artifactForResult = artifactWithoutRetainedWorktree;
       result = {
@@ -451,17 +471,7 @@ export async function runFixSession(
       };
     }
 
-    await emitProgress(options.onProgress, {
-      currentPhase: result.phase,
-      phase: result.phase,
-      sessionStatus: result.sessionStatus,
-      currentAgent: null,
-      selectedFindingIds: result.selection.selectedFindingIds,
-      reviewOutcome: result.reviewOutcome,
-      handoffStatus: result.handoffStatus,
-      handoffId: result.handoffId,
-      handoffUpdatedAt: result.handoffUpdatedAt,
-      commitSha: result.commitSha,
+    await emitResultProgress(options.onProgress, result, {
       worktreeProjectPath: result.retainedWorktree?.worktreeProjectPath,
       worktreeBranch: result.retainedWorktree?.worktreeBranch,
       worktreeMergeReady: result.retainedWorktree?.mergeReady,
@@ -491,17 +501,9 @@ export async function runFixSession(
           (finding) => !selection.selectedFindingIds.includes(finding.id)
         ) ?? [],
     });
-    await emitProgress(options.onProgress, {
+    await emitResultProgress(options.onProgress, result, {
       currentPhase: phase,
-      phase: phase,
-      sessionStatus: result.sessionStatus,
-      currentAgent: null,
-      selectedFindingIds: result.selection.selectedFindingIds,
-      reviewOutcome: result.reviewOutcome,
-      handoffStatus: result.handoffStatus,
-      handoffId: result.handoffId,
-      handoffUpdatedAt: result.handoffUpdatedAt,
-      commitSha: result.commitSha,
+      phase,
       worktreeProjectPath: retainedWorktree?.worktreeProjectPath,
       worktreeBranch: retainedWorktree?.worktreeBranch,
       worktreeMergeReady: retainedWorktree?.mergeReady,

package/src/lib/review-workflow/results/finalize-result.ts

@@ -24,6 +24,9 @@ const DEFAULT_FINALIZE_RESULT_DEPENDENCIES: FinalizeResultDependencies = {
   appendLog,
 };
 
+const MIXED_UNRESOLVED_REASON =
+  "Some selected findings were resolved, but others remain unresolved. Ralph retained the remediation worktree instead of creating a handoff because the partial edits may be unsafe to apply automatically.";
+
 export async function finalizeResult(
   input: FinalizeResultInput,
   deps: FinalizeResultDependencies = DEFAULT_FINALIZE_RESULT_DEPENDENCIES
@@ -39,13 +42,27 @@ export async function finalizeResult(
   const unselectedFindings = input.artifact.findings.filter(
     (finding) => !input.selection.selectedFindingIds.includes(finding.id)
   );
+  const hasResolvedSelectedFindings = input.fixResults.some(
+    (result) => result.status === "resolved"
+  );
+  const hasUnresolvedSelectedFindings = unresolvedSelectedFindings.length > 0;
+  const hasSkippedSelectedFindings = input.fixResults.some((result) => result.status === "skipped");
+  const shouldCreateHandoff = hasResolvedSelectedFindings && !hasUnresolvedSelectedFindings;
 
   let reviewOutcome: FixSessionResult["reviewOutcome"];
   let reason: string;
 
-  if (unresolvedSelectedFindings.length > 0) {
+  if (hasUnresolvedSelectedFindings) {
     reviewOutcome = "incomplete";
-    reason = "Some selected findings remain unresolved after remediation.";
+    reason = hasResolvedSelectedFindings
+      ? MIXED_UNRESOLVED_REASON
+      : "Some selected findings remain unresolved after remediation.";
+  } else if (hasResolvedSelectedFindings) {
+    reviewOutcome = "fixed-selected";
+    reason = "Selected findings were resolved by remediation.";
+  } else if (hasSkippedSelectedFindings) {
+    reviewOutcome = "fixed-selected";
+    reason = "Selected findings were skipped after verification.";
   } else {
     reviewOutcome = "fixed-selected";
     reason = "Selected findings were resolved by remediation.";
@@ -56,7 +73,7 @@ export async function finalizeResult(
   let handoffUpdatedAt: number | undefined;
   let commitSha: string | undefined;
 
-  if (reviewOutcome === "fixed-selected") {
+  if (shouldCreateHandoff) {
     const handoff = await deps.createOrAutoApplyHandoff(undefined, {
       sessionId: input.artifact.sessionId,
       projectPath: input.artifact.projectPath,

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

@@ -24,6 +24,7 @@ import {
   type RunReviewSessionDependencies,
   runReviewSession,
 } from "@/lib/review-workflow/review/run-review-session";
+import { mapSessionStatusToFinalStatus } from "@/lib/review-workflow/session-status";
 import { updateSessionState } from "@/lib/session";
 import { parseFixSummaryOutput, parseReviewSummaryOutput } from "@/lib/structured-output";
 import type {
@@ -203,18 +204,6 @@ function resetInterrupt(): void {
   interrupted = false;
 }
 
-function mapSessionStatusToFinalStatus(status: SessionStatus): CycleResult["finalStatus"] {
-  if (status === "failed") {
-    return "failed";
-  }
-
-  if (status === "interrupted") {
-    return "interrupted";
-  }
-
-  return "completed";
-}
-
 function createSessionEndEntry(
   result: CycleResult | undefined,
   error: unknown,

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

@@ -0,0 +1,13 @@
+import type { SessionEndEntry, SessionStatus } from "@/lib/types";
+
+export function mapSessionStatusToFinalStatus(status: SessionStatus): SessionEndEntry["status"] {
+  if (status === "failed") {
+    return "failed";
+  }
+
+  if (status === "interrupted") {
+    return "interrupted";
+  }
+
+  return "completed";
+}

package/src/lib/review-workflow/shared/framed-json.ts

@@ -1,3 +1,5 @@
+import { removeTrailingCommas } from "@/lib/structured-output";
+
 interface ParseFramedJsonOptions<T> {
   extractedText: string | null;
   rawOutput: string;
@@ -10,53 +12,6 @@ function normalizeCandidate(candidate: string): string {
   return candidate.replace(/\r\n?/g, "\n").trim();
 }
 
-function removeTrailingCommas(candidate: string): string {
-  let output = "";
-  let inString = false;
-  let escaped = false;
-
-  for (let index = 0; index < candidate.length; index += 1) {
-    const char = candidate[index];
-
-    if (escaped) {
-      output += char;
-      escaped = false;
-      continue;
-    }
-
-    if (char === "\\") {
-      output += char;
-      escaped = true;
-      continue;
-    }
-
-    if (char === '"') {
-      output += char;
-      inString = !inString;
-      continue;
-    }
-
-    if (inString || char !== ",") {
-      output += char;
-      continue;
-    }
-
-    let lookahead = index + 1;
-    while (lookahead < candidate.length && /\s/u.test(candidate[lookahead] ?? "")) {
-      lookahead += 1;
-    }
-
-    const nextChar = candidate[lookahead];
-    if (nextChar === "}" || nextChar === "]") {
-      continue;
-    }
-
-    output += char;
-  }
-
-  return output;
-}
-
 function extractFramedPayload(output: string, startToken: string, endToken: string): string | null {
   const normalized = normalizeCandidate(output);
   const startIndex = normalized.indexOf(startToken);

package/src/lib/session/state.ts

@@ -45,34 +45,39 @@ interface SessionStateGuardOptions {
   expectedSessionId?: string;
 }
 
-interface CreateSessionStateOptions {
-  branch?: string;
+interface CreateSessionStateOptions
+  extends Partial<
+    Pick<
+      SessionState,
+      | "branch"
+      | "state"
+      | "mode"
+      | "pid"
+      | "startTime"
+      | "lastHeartbeat"
+      | "sessionPath"
+      | "worktreeProjectPath"
+      | "worktreeBranch"
+      | "worktreeMergeReady"
+      | "worktreeCommitSha"
+      | "endTime"
+      | "reason"
+      | "currentPhase"
+      | "phase"
+      | "sessionStatus"
+      | "reviewOutcome"
+      | "handoffStatus"
+      | "handoffId"
+      | "handoffUpdatedAt"
+      | "commitSha"
+      | "artifactPath"
+      | "baselineCommitSha"
+      | "sourceBaselineFingerprint"
+      | "accumulatedFindings"
+      | "selectedFindingIds"
+    >
+  > {
   sessionId: string;
-  state?: SessionStatus;
-  mode?: SessionMode;
-  pid?: number;
-  startTime?: number;
-  lastHeartbeat?: number;
-  sessionPath?: string;
-  worktreeProjectPath?: string;
-  worktreeBranch?: string;
-  worktreeMergeReady?: boolean;
-  worktreeCommitSha?: string;
-  endTime?: number;
-  reason?: string;
-  currentPhase?: ReviewPhase;
-  phase?: ReviewPhase;
-  sessionStatus?: WorkflowSessionStatus;
-  reviewOutcome?: ReviewOutcome;
-  handoffStatus?: HandoffStatus;
-  handoffId?: string;
-  handoffUpdatedAt?: number;
-  commitSha?: string;
-  artifactPath?: string;
-  baselineCommitSha?: string;
-  sourceBaselineFingerprint?: string;
-  accumulatedFindings?: StoredFinding[];
-  selectedFindingIds?: FindingId[];
 }
 
 export interface SessionState {
@@ -201,17 +206,28 @@ async function readSessionStateByPath(sessionStatePath: string): Promise<Session
   }
 }
 
+async function readExpectedSessionStateByPath(
+  sessionStatePath: string,
+  options: SessionStateGuardOptions
+): Promise<SessionState | null> {
+  const existing = await readSessionStateByPath(sessionStatePath);
+  if (!existing) {
+    return null;
+  }
+
+  if (options.expectedSessionId && existing.sessionId !== options.expectedSessionId) {
+    return null;
+  }
+
+  return existing;
+}
+
 async function removeSessionStateByPath(
   sessionStatePath: string,
   options: SessionStateGuardOptions = {}
 ): Promise<boolean> {
   return queueSessionStateWrite(sessionStatePath, async () => {
-    const existing = await readSessionStateByPath(sessionStatePath);
-    if (!existing) {
-      return false;
-    }
-
-    if (options.expectedSessionId && existing.sessionId !== options.expectedSessionId) {
+    if (!(await readExpectedSessionStateByPath(sessionStatePath, options))) {
       return false;
     }
 
@@ -351,15 +367,11 @@ export async function updateSessionState(
   const sessionStatePath = getSessionStatePath(storageRoot, projectPath, sessionId);
 
   return await queueSessionStateWrite(sessionStatePath, async () => {
-    const existing = await readSessionStateByPath(sessionStatePath);
+    const existing = await readExpectedSessionStateByPath(sessionStatePath, options);
     if (!existing) {
       return false;
     }
 
-    if (options.expectedSessionId && existing.sessionId !== options.expectedSessionId) {
-      return false;
-    }
-
     const merged = { ...existing } as Record<string, unknown>;
     for (const [key, value] of Object.entries(updates)) {
       if (value === undefined) {

package/src/lib/structured-output.ts

@@ -42,6 +42,12 @@ interface RepairedCandidate {
   changed: boolean;
 }
 
+export interface JsonObjectSlice {
+  start: number;
+  end: number;
+  value: string;
+}
+
 function normalizeCandidateText(candidate: string): string {
   return candidate
     .replace(/^\uFEFF/, "")
@@ -72,8 +78,8 @@ function extractJsonBlock(output: string): string | null {
   return match[1].trim();
 }
 
-function extractBalancedJsonObjects(text: string): string[] {
-  const objects: string[] = [];
+export function extractBalancedJsonObjectSlices(text: string): JsonObjectSlice[] {
+  const objects: JsonObjectSlice[] = [];
   let depth = 0;
   let startIndex = -1;
   let inString = false;
@@ -87,12 +93,12 @@ function extractBalancedJsonObjects(text: string): string[] {
       continue;
     }
 
-    if (char === "\\") {
-      escaped = true;
-      continue;
-    }
-
     if (inString) {
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+
       if (char === '"') {
         inString = false;
       }
@@ -122,7 +128,12 @@ function extractBalancedJsonObjects(text: string): string[] {
 
     depth -= 1;
     if (depth === 0 && startIndex >= 0) {
-      objects.push(text.slice(startIndex, index + 1));
+      const endIndex = index + 1;
+      objects.push({
+        start: startIndex,
+        end: endIndex,
+        value: text.slice(startIndex, endIndex),
+      });
       startIndex = -1;
     }
   }
@@ -130,6 +141,10 @@ function extractBalancedJsonObjects(text: string): string[] {
   return objects;
 }
 
+function extractBalancedJsonObjects(text: string): string[] {
+  return extractBalancedJsonObjectSlices(text).map((object) => object.value);
+}
+
 function isolateJsonObject(candidate: string): string {
   const objects = extractBalancedJsonObjects(candidate);
   if (objects.length === 0) {
@@ -140,7 +155,7 @@ function isolateJsonObject(candidate: string): string {
   return lastObject?.trim() || candidate;
 }
 
-function removeTrailingCommas(candidate: string): string {
+export function removeTrailingCommas(candidate: string): string {
   let output = "";
   let inString = false;
   let escaped = false;

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

@@ -1,5 +1,5 @@
 import { useKeyboard } from "@opentui/react";
-import { TUI_COLORS } from "@/lib/tui/shared/colors";
+import { KeyboardShortcutsModal } from "@/lib/tui/shared/KeyboardShortcutsModal";
 
 interface HelpOverlayProps {
   onClose: () => void;
@@ -12,60 +12,16 @@ export function HelpOverlay({ onClose }: HelpOverlayProps) {
     }
   });
 
-  return (
-    <box
-      position="absolute"
-      left={0}
-      top={0}
-      width="100%"
-      height="100%"
-      justifyContent="center"
-      alignItems="center"
-    >
-      <box
-        border
-        borderStyle="double"
-        title="Keyboard Shortcuts"
-        titleAlignment="left"
-        padding={2}
-        width={44}
-        backgroundColor="#1a1a2e"
-      >
-        <box flexDirection="column" gap={1}>
-          <text>
-            <span fg={TUI_COLORS.accent.key}>[r]</span>
-            <span fg={TUI_COLORS.text.muted}> Run new review session</span>
-          </text>
-          <text>
-            <span fg={TUI_COLORS.accent.key}>[s]</span>
-            <span fg={TUI_COLORS.text.muted}> Stop running review session</span>
-          </text>
-          <text>
-            <span fg={TUI_COLORS.accent.key}>[o]</span>
-            <span fg={TUI_COLORS.text.muted}> Toggle output drawer</span>
-          </text>
-          <text>
-            <span fg={TUI_COLORS.accent.key}>[Tab ←/→]</span>
-            <span fg={TUI_COLORS.text.muted}> Switch panel focus</span>
-          </text>
-          <text>
-            <span fg={TUI_COLORS.accent.key}>[↑/↓ j/k]</span>
-            <span fg={TUI_COLORS.text.muted}> Scroll focused panel</span>
-          </text>
-          <text>
-            <span fg={TUI_COLORS.accent.key}>[l]</span>
-            <span fg={TUI_COLORS.text.muted}> View logs</span>
-          </text>
-          <text>
-            <span fg={TUI_COLORS.accent.key}>[Esc/q]</span>
-            <span fg={TUI_COLORS.text.muted}> Quit TUI (Won't stop review)</span>
-          </text>
-          <text>
-            <span fg={TUI_COLORS.accent.key}>[h/?]</span>
-            <span fg={TUI_COLORS.text.muted}> Toggle help</span>
-          </text>
-        </box>
-      </box>
-    </box>
-  );
+  return <KeyboardShortcutsModal shortcuts={DASHBOARD_SHORTCUTS} />;
 }
+
+const DASHBOARD_SHORTCUTS = [
+  { keys: "[r]", label: "Run new review session" },
+  { keys: "[s]", label: "Stop running review session" },
+  { keys: "[o]", label: "Toggle output drawer" },
+  { keys: "[Tab ←/→]", label: "Switch panel focus" },
+  { keys: "[↑/↓ j/k]", label: "Scroll focused panel" },
+  { keys: "[l]", label: "View logs" },
+  { keys: "[Esc/q]", label: "Quit TUI (Won't stop review)" },
+  { keys: "[h/?]", label: "Toggle help" },
+] as const;