ralph-review 0.2.2 → 0.2.4

package/src/commands/stop.ts

@@ -1,5 +1,9 @@
-import * as p from "@clack/prompts";
-import { getCommandDef } from "@/cli";
+import {
+  createInteractiveCommandDeps,
+  createPromptDeps,
+  type InteractiveCommandDeps,
+  type PromptDeps,
+} from "@/commands/interactive-deps";
 import { parseCommand } from "@/lib/cli-parser";
 import { listProjectPendingHandoffs } from "@/lib/handoff";
 import { formatHandoffNote } from "@/lib/handoff-note";
@@ -22,18 +26,46 @@ interface StopOptions {
   session?: string;
 }
 
-interface StopDeps {
-  getCommandDef: typeof getCommandDef;
-  logError: (message: string) => void;
-  exit: (code: number) => void;
-  isTTY: () => boolean;
-}
+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: StopDeps = {
-  getCommandDef,
-  logError: (message: string) => p.log.error(message),
-  exit: (code: number) => process.exit(code),
-  isTTY: () => process.stdout.isTTY === true,
+  ...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 = {
@@ -97,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)
@@ -119,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
     );
@@ -160,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;
   }
@@ -188,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(
@@ -240,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,
@@ -251,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)
@@ -292,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(
@@ -332,7 +367,7 @@ async function stopCurrentProjectSession(
   deps: StopDeps
 ): Promise<void> {
   const projectSessions = getCurrentProjectSessions(
-    await listProjectActiveSessions(undefined, projectPath),
+    await deps.listProjectActiveSessions(undefined, projectPath),
     projectPath
   );
 
@@ -344,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.'
       );
     }
@@ -364,7 +399,7 @@ async function stopCurrentProjectSession(
   if (projectSessions.length === 1) {
     const onlySession = projectSessions[0];
     if (onlySession) {
-      await stopSession(onlySession);
+      await stopSession(onlySession, deps);
     }
     return;
   }
@@ -377,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> {
@@ -406,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/commands/update.ts

@@ -1,5 +1,6 @@
 import * as p from "@clack/prompts";
 import { getCommandDef } from "@/cli";
+import type { SpinnerFactory } from "@/cli-io";
 import { type CommandDef, parseCommand } from "@/lib/cli-parser";
 import {
   getDefaultSelfUpdateDependencies,
@@ -16,10 +17,7 @@ interface UpdateRuntime extends SelfUpdateDependencies {
   getCommandDef: (name: string) => CommandDef | undefined;
   parseCommand: typeof parseCommand;
   performSelfUpdate: typeof performSelfUpdate;
-  spinner: () => {
-    start: (message: string) => void;
-    stop: (message: string) => void;
-  };
+  spinner: SpinnerFactory;
   log: {
     error: (message: string) => void;
     info: (message: string) => void;

package/src/lib/agents/claude.ts

@@ -3,7 +3,7 @@
  */
 
 import type { AgentConfig, AgentRole, ReviewOptions } from "@/lib/types";
-import { createLineFormatter, parseJsonlEvent } from "./core";
+import { createLineFormatter, extractLastParsedValue, parseJsonlEvent } from "./core";
 import type {
   AssistantContentBlock,
   AssistantEvent,
@@ -128,21 +128,9 @@ export function formatClaudeEventForDisplay(event: ClaudeStreamEvent): string |
 }
 
 export function extractClaudeResult(output: string): string | null {
-  if (!output.trim()) {
-    return null;
-  }
-
-  const lines = output.split("\n");
-  let lastResult: string | null = null;
-
-  for (const line of lines) {
-    const event = parseClaudeStreamEvent(line);
-    if (event && isResultEvent(event)) {
-      lastResult = event.result;
-    }
-  }
-
-  return lastResult;
+  return extractLastParsedValue(output, parseClaudeStreamEvent, (event) =>
+    isResultEvent(event) ? event.result : null
+  );
 }
 
 export const formatClaudeLine = createLineFormatter(

package/src/lib/agents/core.ts

@@ -46,6 +46,22 @@ export function createLineFormatter<T>(
   };
 }
 
+export function extractLastParsedValue<T>(
+  output: string,
+  parser: (line: string) => T | null,
+  selectValue: (event: T) => string | null
+): string | null {
+  if (!output.trim()) {
+    return null;
+  }
+
+  return output.split("\n").reduce<string | null>((lastResult, line) => {
+    const event = parser(line);
+    const value = event ? selectValue(event) : null;
+    return value ?? lastResult;
+  }, null);
+}
+
 export function stripSystemReminders(text: unknown): string {
   const normalized = typeof text === "string" ? text : String(text ?? "");
   return normalized.replace(/<system-reminder>[\s\S]*?<\/system-reminder>\s*/g, "").trim();

package/src/lib/agents/droid.ts

@@ -11,6 +11,7 @@ import {
 import {
   createLineFormatter,
   defaultBuildEnv,
+  extractLastParsedValue,
   parseJsonlEvent,
   stripSystemReminders,
 } from "./core";
@@ -109,21 +110,9 @@ export function formatDroidEventForDisplay(event: DroidStreamEvent): string | nu
 }
 
 export function extractDroidResult(output: string): string | null {
-  if (!output.trim()) {
-    return null;
-  }
-
-  const lines = output.split("\n");
-  let lastResult: string | null = null;
-
-  for (const line of lines) {
-    const event = parseDroidStreamEvent(line);
-    if (event?.type === "completion") {
-      lastResult = event.finalText;
-    }
-  }
-
-  return lastResult;
+  return extractLastParsedValue(output, parseDroidStreamEvent, (event) =>
+    event.type === "completion" ? event.finalText : null
+  );
 }
 
 export const formatDroidLine = createLineFormatter(

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/cli-parser.ts

@@ -162,6 +162,23 @@ function consumeOptionValue(
   throw new Error(`Option --${opt.name} requires a value`);
 }
 
+function assignOptionValue(
+  values: Record<string, unknown>,
+  opt: OptionDef,
+  argv: string[],
+  currentIndex: number,
+  inlineValue?: string
+): number {
+  if (opt.type === "boolean") {
+    values[opt.name] = true;
+    return currentIndex;
+  }
+
+  const { value, nextIndex } = consumeOptionValue(opt, argv, currentIndex, inlineValue);
+  values[opt.name] = parseValue(opt, value);
+  return nextIndex;
+}
+
 export function parseCommand<T = Record<string, unknown>>(
   def: CommandDef,
   argv: string[]
@@ -216,13 +233,7 @@ export function parseCommand<T = Record<string, unknown>>(
         throw new CliError(def.name, "unknown_option", arg, validOptions, suggestion);
       }
 
-      if (opt.type === "boolean") {
-        values[opt.name] = true;
-      } else {
-        const { value, nextIndex } = consumeOptionValue(opt, argv, i, inlineValue);
-        i = nextIndex;
-        values[opt.name] = parseValue(opt, value);
-      }
+      i = assignOptionValue(values, opt, argv, i, inlineValue);
 
       i++;
       continue;
@@ -249,13 +260,7 @@ export function parseCommand<T = Record<string, unknown>>(
         throw new CliError(def.name, "unknown_option", `-${alias}`, validOptions);
       }
 
-      if (opt.type === "boolean") {
-        values[opt.name] = true;
-      } else {
-        const { value, nextIndex } = consumeOptionValue(opt, argv, i);
-        i = nextIndex;
-        values[opt.name] = parseValue(opt, value);
-      }
+      i = assignOptionValue(values, opt, argv, i);
 
       i++;
       continue;

package/src/lib/handoff.ts

@@ -386,8 +386,8 @@ export async function listProjectPendingHandoffs(
   );
 }
 
-export async function applyPendingHandoff(
-  storageRoot: string = CONFIG_DIR,
+async function requirePendingHandoff(
+  storageRoot: string,
   projectPath: string,
   handoffId: string
 ): Promise<PendingHandoffArtifact> {
@@ -396,7 +396,19 @@ export async function applyPendingHandoff(
     throw new Error(`Pending review handoff "${handoffId}" was not found.`);
   }
 
-  return await applyPendingHandoffArtifact(storageRoot, artifact, "manual");
+  return artifact;
+}
+
+export async function applyPendingHandoff(
+  storageRoot: string = CONFIG_DIR,
+  projectPath: string,
+  handoffId: string
+): Promise<PendingHandoffArtifact> {
+  return await applyPendingHandoffArtifact(
+    storageRoot,
+    await requirePendingHandoff(storageRoot, projectPath, handoffId),
+    "manual"
+  );
 }
 
 export async function discardPendingHandoff(
@@ -404,10 +416,7 @@ export async function discardPendingHandoff(
   projectPath: string,
   handoffId: string
 ): Promise<PendingHandoffArtifact> {
-  const artifact = await readPendingHandoff(storageRoot, projectPath, handoffId);
-  if (!artifact) {
-    throw new Error(`Pending review handoff "${handoffId}" was not found.`);
-  }
+  const artifact = await requirePendingHandoff(storageRoot, projectPath, handoffId);
 
   if (artifact.state === "apply-conflicted") {
     throw new Error(

package/src/lib/logging/session-log.ts

@@ -517,6 +517,7 @@ function applyEntryToSummary(
     const unresolvedFindings = entry.fixResults.filter(
       (result) => result.status === "unresolved"
     ).length;
+    const skippedFindings = entry.fixResults.filter((result) => result.status === "skipped").length;
     const failed = entry.error !== undefined;
     const interrupted = entry.error?.message.toLowerCase().includes("interrupt") === true;
 
@@ -528,7 +529,7 @@ function applyEntryToSummary(
     next.totalResolvedSelectedFindings = resolvedFindings;
     next.totalUnresolvedSelectedFindings = unresolvedFindings;
     next.totalFixes = resolvedFindings;
-    next.totalSkipped = unresolvedFindings;
+    next.totalSkipped = skippedFindings + unresolvedFindings;
 
     if (entry.duration !== undefined) {
       next.totalDuration = (summary.totalDuration ?? 0) + entry.duration;

package/src/lib/prompts/defaults/review.md

@@ -89,6 +89,6 @@ Use this strict framing protocol:
 
 * **Do not** wrap the JSON in markdown fences or extra prose.
 * The code_location field is required and must include absolute_file_path and line_range.
-* Line ranges must be as short as possible for interpreting the issue (avoid ranges over 5–10 lines; pick the most suitable subrange).
+* Line ranges must use integer `start` and `end` values with `end >= start`, and must be as short as possible for interpreting the issue (avoid ranges over 5–10 lines; pick the most suitable subrange).
 * The code_location should overlap with the diff.
 * Do not generate a PR fix.

package/src/lib/prompts/protocol.ts

@@ -11,7 +11,8 @@ export function createReviewerStructuredOutputInstructions(): string {
   - ${REVIEW_SUMMARY_START_TOKEN}
   - ${REVIEW_SUMMARY_END_TOKEN}
 - Do not include markdown fences.
-- Do not include any text before the start token or after the end token.`;
+- Do not include any text before the start token or after the end token.
+- For each finding code_location.line_range, start and end MUST be integers and end MUST be greater than or equal to start.`;
 }
 
 export function createFixerStructuredOutputInstructions(): string {

package/src/lib/review-workflow/findings/artifact.ts

@@ -79,7 +79,9 @@ function isFixResultArray(value: unknown): value is FindingFixResult[] {
 
     return (
       isFindingId(entry.findingId) &&
-      (entry.status === "resolved" || entry.status === "unresolved") &&
+      (entry.status === "resolved" ||
+        entry.status === "skipped" ||
+        entry.status === "unresolved") &&
       typeof entry.summary === "string"
     );
   });

package/src/lib/review-workflow/findings/types.ts

@@ -19,7 +19,7 @@ export interface StoredFinding {
 
 export interface FindingFixResult {
   findingId: FindingId;
-  status: "resolved" | "unresolved";
+  status: "resolved" | "skipped" | "unresolved";
   summary: string;
 }
 

package/src/lib/review-workflow/remediation/prompt.ts

@@ -213,7 +213,7 @@ ${formatSelectedFindings(options.selectedFindings)}
 
 ## Required workflow
 1. Verify each selected finding independently against the real code.
-2. Decide resolved vs unresolved for each finding before making edits.
+2. Decide resolved vs skipped vs unresolved for each finding before making edits.
 3. Apply fixes only for findings you can prove.
 4. Keep edits as local and minimal as possible.
 5. Return one result entry for every selected finding ID.
@@ -231,8 +231,8 @@ ${FIX_SUMMARY_START_TOKEN}
   "decision": "<NO_CHANGES_NEEDED | APPLY_SELECTIVELY | APPLY_MOST>",
   "results": {
     "F001": {
-      "status": "<resolved | unresolved>",
-      "summary": "<what changed or why the finding remains unresolved>"
+      "status": "<resolved | skipped | unresolved>",
+      "summary": "<what changed or why the finding was skipped or remains unresolved>"
     }
   }
 }
@@ -240,11 +240,11 @@ ${FIX_SUMMARY_END_TOKEN}
 
 JSON rules:
 - Use the selected finding IDs as the object keys under \`results\`.
-- Return \`resolved\` only when the selected finding is fully addressed or already satisfied by the current code.
-- Return \`unresolved\` when the finding still needs follow-up, including when you skip it for lack of proof or cannot safely remediate it.
+- Return \`resolved\` only when the selected finding is verified and fixed; intentional edits may be included in a handoff.
+- Return \`skipped\` only when the selected finding is not actionable or not proven and does not require a code change.
+- Return \`unresolved\` when the finding is likely actionable or you attempted a fix but cannot safely complete and verify it.
 - You must return one result entry for every selected finding ID.
 - Do not include any finding that was not selected.
-- Use \`resolved\` only when you verified the issue and applied a real code change.
-- Use \`unresolved\` when the finding was unproven, out of scope, or did not require a safe change.
+- Missing result entries will be treated as \`unresolved\`.
 - The delimited JSON block must be the final output.`;
 }