ralph-review 0.1.7 → 0.1.9

package/README.md

@@ -162,6 +162,7 @@ rrr
 
 | Command | Description |
 |---------|-------------|
+| `rr` | Interactive Mode |
 | `rr init` | Configure reviewer, fixer, and simplifier agents (auto-detects installed CLIs) |
 | `rr run` | Start review cycle in a tmux session |
 | `rr run --base main` | Review changes against a base branch |
@@ -172,7 +173,6 @@ rrr
 | `rr config show` | Print full configuration |
 | `rr config set KEY VAL` | Update a config value (e.g. `rr config set maxIterations 8`) |
 | `rr list` | List active review sessions |
-| `rr status` | Show current review status |
 | `rr stop` | Stop running review session (`--all` to stop all) |
 | `rr log` | View review logs (`-n 5` for last 5, `--json` for JSON output) |
 | `rr dashboard` | Open review dashboard in browser |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-review",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Orchestrating coding agents for code review, verification and fixing via the ralph loop.",
   "license": "MIT",
   "type": "module",

package/src/cli-core.ts

@@ -81,18 +81,18 @@ export const COMMANDS: CommandDef[] = [
         description: "Disable finish sound for this run (override config)",
       },
       {
-        name: "watch",
+        name: "interactive",
         type: "boolean",
-        description: "Open Session Panel after starting the run (override config)",
+        description: "Launch Interactive Mode after starting the run (override config)",
       },
       {
-        name: "no-watch",
+        name: "no-interactive",
         type: "boolean",
-        description: "Start run without opening Session Panel (override config)",
+        description: "Start run without launching Interactive Mode (override config)",
       },
       SIMPLIFIER_OPTION,
     ],
-    examples: ["rr run", "rr run --base main", "rr run --no-watch"],
+    examples: ["rr run", "rr run --base main", "rr run --no-interactive"],
   },
   {
     name: "list",
@@ -104,6 +104,7 @@ export const COMMANDS: CommandDef[] = [
     name: "status",
     description: "Show review status",
     examples: ["rr status"],
+    hidden: true,
   },
   {
     name: "stop",

package/src/cli.ts

@@ -43,6 +43,7 @@ export interface CliDeps {
   runDoctor: typeof runDoctor;
   runList: typeof runList;
   runUpdate: typeof runUpdate;
+  isInteractiveTerminal: () => boolean;
   log: (message: string) => void;
   logError: (message: string) => void;
   logMessage: (message: string) => void;
@@ -53,6 +54,8 @@ const CONSOLE_LOG = console.log.bind(console) as (message: string) => void;
 const CLACK_ERROR = p.log.error.bind(p.log) as (message: string) => void;
 const CLACK_MESSAGE = p.log.message.bind(p.log) as (message: string) => void;
 const PROCESS_EXIT = process.exit.bind(process) as (code: number) => void;
+const IS_INTERACTIVE_TERMINAL = (): boolean =>
+  process.stdin.isTTY === true && process.stdout.isTTY === true;
 
 const DEFAULT_CLI_DEPS: CliDeps = {
   parseArgs,
@@ -72,6 +75,7 @@ const DEFAULT_CLI_DEPS: CliDeps = {
   runDoctor,
   runList,
   runUpdate,
+  isInteractiveTerminal: IS_INTERACTIVE_TERMINAL,
   log: CONSOLE_LOG,
   logError: CLACK_ERROR,
   logMessage: CLACK_MESSAGE,
@@ -82,6 +86,11 @@ function buildCliDeps(overrides: Partial<CliDeps>): CliDeps {
   return { ...DEFAULT_CLI_DEPS, ...overrides };
 }
 
+function reportCliError(cliDeps: CliDeps, error: unknown): void {
+  cliDeps.logError(`Error: ${error}`);
+  cliDeps.exit(1);
+}
+
 export async function runCli(
   args: string[] = process.argv.slice(2),
   deps: Partial<CliDeps> = {}
@@ -94,11 +103,25 @@ export async function runCli(
     return;
   }
 
-  if (!command) {
+  if (showHelp && !command) {
     cliDeps.log(cliDeps.printUsage());
     return;
   }
 
+  if (!command) {
+    if (commandArgs.length > 0 || !cliDeps.isInteractiveTerminal()) {
+      cliDeps.log(cliDeps.printUsage());
+      return;
+    }
+
+    try {
+      await cliDeps.runStatus();
+    } catch (error) {
+      reportCliError(cliDeps, error);
+    }
+    return;
+  }
+
   if (showHelp) {
     const commandHelp = cliDeps.printCommandHelp(command);
     if (commandHelp) {
@@ -183,8 +206,7 @@ export async function runCli(
         return;
     }
   } catch (error) {
-    cliDeps.logError(`Error: ${error}`);
-    cliDeps.exit(1);
+    reportCliError(cliDeps, error);
   }
 }
 

package/src/commands/config.ts

@@ -4,7 +4,9 @@ import {
   configExists,
   ensureConfigDir,
   loadConfig,
+  loadConfigWithDiagnostics,
   parseConfig,
+  parseConfigWithDiagnostics,
   saveConfig,
 } from "@/lib/config";
 import {
@@ -41,7 +43,9 @@ export type ConfigCommandDeps = {
   configExists: typeof configExists;
   ensureConfigDir: typeof ensureConfigDir;
   loadConfig: typeof loadConfig;
+  loadConfigWithDiagnostics: typeof loadConfigWithDiagnostics;
   parseConfig: typeof parseConfig;
+  parseConfigWithDiagnostics: typeof parseConfigWithDiagnostics;
   saveConfig: typeof saveConfig;
   spawn: ConfigCommandSpawner;
   env: Record<string, string | undefined>;
@@ -68,7 +72,7 @@ const CONFIG_KEYS = [
   "defaultReview.type",
   "defaultReview.branch",
   "run.simplifier",
-  "run.watch",
+  "run.interactive",
   "retry.maxRetries",
   "retry.baseDelayMs",
   "retry.maxDelayMs",
@@ -251,7 +255,7 @@ export function parseConfigValue(key: ConfigKey, rawValue: string): ConfigValue
       return rawValue;
 
     case "run.simplifier":
-    case "run.watch":
+    case "run.interactive":
       if (rawValue !== "true" && rawValue !== "false") {
         throw new Error(`Value for "${key}" must be "true" or "false".`);
       }
@@ -306,8 +310,8 @@ export function getConfigValue(config: Config, key: ConfigKey): unknown {
       return config.defaultReview.type === "base" ? config.defaultReview.branch : undefined;
     case "run.simplifier":
       return config.run?.simplifier;
-    case "run.watch":
-      return config.run?.watch;
+    case "run.interactive":
+      return config.run?.interactive;
     case "retry.maxRetries":
       return config.retry?.maxRetries;
     case "retry.baseDelayMs":
@@ -490,13 +494,13 @@ export function setConfigValue(config: Config, key: ConfigKey, value: ConfigValu
       if (typeof value !== "boolean") {
         throw new Error(`Value for "${key}" must be "true" or "false".`);
       }
-      next.run = { simplifier: value, watch: next.run?.watch ?? true };
+      next.run = { simplifier: value, interactive: next.run?.interactive ?? true };
       return next;
-    case "run.watch":
+    case "run.interactive":
       if (typeof value !== "boolean") {
         throw new Error(`Value for "${key}" must be "true" or "false".`);
       }
-      next.run = { simplifier: next.run?.simplifier ?? false, watch: value };
+      next.run = { simplifier: next.run?.simplifier ?? false, interactive: value };
       return next;
     case "retry.maxRetries":
       next.retry = next.retry ? { ...next.retry } : { ...DEFAULT_RETRY_CONFIG };
@@ -591,26 +595,55 @@ export function validateConfigInvariants(config: Config): string[] {
   if (config.run && typeof config.run.simplifier !== "boolean") {
     errors.push("run.simplifier must be a boolean.");
   }
-  if (config.run && typeof config.run.watch !== "boolean") {
-    errors.push("run.watch must be a boolean.");
+  if (config.run && typeof config.run.interactive !== "boolean") {
+    errors.push("run.interactive must be a boolean.");
   }
 
   return errors;
 }
 
+function formatConfigValidationMessage(header: string, errors: string[], footer?: string): string {
+  const uniqueErrors = [...new Set(errors)];
+  const lines = [header];
+  for (const error of uniqueErrors) {
+    lines.push(`- ${error}`);
+  }
+  if (footer) {
+    lines.push(footer);
+  }
+  return lines.join("\n");
+}
+
+function collectConfigValidationErrors(config: Config | null, errors: string[]): string[] {
+  const combined = [...errors];
+  if (config) {
+    combined.push(...validateConfigInvariants(config));
+  }
+  return [...new Set(combined)];
+}
+
 async function loadExistingConfig(deps: ConfigCommandDeps): Promise<Config> {
   if (!(await deps.configExists())) {
     throw new Error('Configuration not found. Run "rr init" first.');
   }
 
-  const config = await deps.loadConfig();
-  if (!config) {
+  const loaded = await deps.loadConfigWithDiagnostics();
+  if (!loaded.exists) {
+    throw new Error('Configuration not found. Run "rr init" first.');
+  }
+
+  const errors = collectConfigValidationErrors(loaded.config, loaded.errors);
+  if (!loaded.config || errors.length > 0) {
     throw new Error(
-      `Configuration exists but is invalid: ${deps.configPath}. Run "rr init" or fix the file manually.`
+      formatConfigValidationMessage(
+        `Invalid configuration: ${deps.configPath}`,
+        errors.length > 0 ? errors : ["Configuration format is invalid."],
+        'Run "rr init" to regenerate the file, or fix it manually.'
+      )
     );
   }
 
-  return config;
+  return loaded.config;
 }
 
 async function runShow(args: string[], deps: ConfigCommandDeps): Promise<void> {
@@ -650,17 +683,18 @@ async function runSet(args: string[], deps: ConfigCommandDeps): Promise<void> {
   const current = await loadExistingConfig(deps);
   const updated = setConfigValue(current, key, parsedValue);
 
-  const invariantErrors = validateConfigInvariants(updated);
-  if (invariantErrors.length > 0) {
-    throw new Error(invariantErrors.join("\n"));
-  }
-
-  const normalized = deps.parseConfig(updated as unknown);
-  if (!normalized) {
-    throw new Error("Updated configuration is invalid.");
+  const normalized = deps.parseConfigWithDiagnostics(updated as unknown);
+  const validationErrors = collectConfigValidationErrors(normalized.config, normalized.errors);
+  if (!normalized.config || validationErrors.length > 0) {
+    throw new Error(
+      formatConfigValidationMessage(
+        "Updated configuration is invalid.",
+        validationErrors.length > 0 ? validationErrors : ["Configuration format is invalid."]
+      )
+    );
   }
 
-  await deps.saveConfig(normalized);
+  await deps.saveConfig(normalized.config);
   deps.log.success(`Updated "${key}" to ${formatValue(parsedValue)}.`);
 }
 
@@ -695,15 +729,20 @@ async function runEdit(args: string[], deps: ConfigCommandDeps): Promise<void> {
     return;
   }
 
-  const config = await deps.loadConfig();
-  if (!config) {
+  const loaded = await deps.loadConfigWithDiagnostics();
+  const errors = collectConfigValidationErrors(loaded.config, loaded.errors);
+  if (!loaded.config || errors.length > 0) {
     deps.log.warn(
-      `Configuration exists but is invalid: ${deps.configPath}. Run "rr init" or fix it manually.`
+      formatConfigValidationMessage(
+        `Invalid configuration: ${deps.configPath}`,
+        errors.length > 0 ? errors : ["Configuration format is invalid."],
+        'Run "rr init" to regenerate the file, or fix it manually.'
+      )
     );
     return;
   }
 
-  await deps.saveConfig(config);
+  await deps.saveConfig(loaded.config);
 }
 
 const DEFAULT_CONFIG_COMMAND_DEPS: ConfigCommandDeps = {
@@ -711,7 +750,9 @@ const DEFAULT_CONFIG_COMMAND_DEPS: ConfigCommandDeps = {
   configExists,
   ensureConfigDir,
   loadConfig,
+  loadConfigWithDiagnostics,
   parseConfig,
+  parseConfigWithDiagnostics,
   saveConfig,
   spawn: Bun.spawn as unknown as ConfigCommandSpawner,
   env: process.env as Record<string, string | undefined>,
@@ -731,7 +772,7 @@ function resolveConfigCommandDeps(overrides?: Partial<ConfigCommandDeps>): Confi
     return DEFAULT_CONFIG_COMMAND_DEPS;
   }
 
-  return {
+  const deps: ConfigCommandDeps = {
     ...DEFAULT_CONFIG_COMMAND_DEPS,
     ...overrides,
     log: {
@@ -739,6 +780,30 @@ function resolveConfigCommandDeps(overrides?: Partial<ConfigCommandDeps>): Confi
       ...overrides.log,
     },
   };
+
+  const loadConfigOverride = overrides.loadConfig;
+  if (loadConfigOverride && !overrides.loadConfigWithDiagnostics) {
+    deps.loadConfigWithDiagnostics = async (path = deps.configPath) => {
+      const config = (await loadConfigOverride(path)) ?? null;
+      return {
+        exists: config !== null,
+        config,
+        errors: config ? [] : ["Configuration format is invalid."],
+      };
+    };
+  }
+
+  if (overrides.parseConfig && !overrides.parseConfigWithDiagnostics) {
+    deps.parseConfigWithDiagnostics = (value) => {
+      const config = overrides.parseConfig?.(value) ?? null;
+      return {
+        config,
+        errors: config ? [] : ["Configuration format is invalid."],
+      };
+    };
+  }
+
+  return deps;
 }
 
 export function createRunConfig(overrides?: Partial<ConfigCommandDeps>) {

package/src/commands/init.ts

@@ -53,7 +53,7 @@ interface InitInput {
   defaultReviewType: "uncommitted" | "base";
   defaultReviewBranch?: string;
   runSimplifierByDefault: boolean;
-  runWatchByDefault: boolean;
+  runInteractiveByDefault: boolean;
   soundNotificationsEnabled: boolean;
 }
 
@@ -319,7 +319,7 @@ export function buildConfig(input: InitInput): Config {
     ),
     run: {
       simplifier: input.runSimplifierByDefault,
-      watch: input.runWatchByDefault,
+      interactive: input.runInteractiveByDefault,
     },
     maxIterations: input.maxIterations,
     iterationTimeout: input.iterationTimeoutMinutes * 60 * 1000,
@@ -537,7 +537,7 @@ function formatConfigDisplay(config: Config): string {
     `  Iteration timeout:   ${config.iterationTimeout / 1000 / 60} minutes`,
     `  Default review:      ${defaultReviewDisplay}`,
     `  Run simplifier:      ${config.run?.simplifier ? "enabled" : "disabled"}`,
-    `  Run watch panel:     ${(config.run?.watch ?? true) ? "enabled" : "disabled"}`,
+    `  Interactive Mode:    ${(config.run?.interactive ?? true) ? "enabled" : "disabled"}`,
     `  Sound notify:        ${config.notifications.sound.enabled ? "enabled" : "disabled"}`,
   ].join("\n");
 }
@@ -757,7 +757,7 @@ export async function buildAutoInitInput(
       iterationTimeoutMinutes,
       defaultReviewType: "uncommitted",
       runSimplifierByDefault: false,
-      runWatchByDefault: true,
+      runInteractiveByDefault: true,
       soundNotificationsEnabled: true,
     },
     skippedAgents,
@@ -919,14 +919,17 @@ async function promptForCustomInitInput(
     defaultReviewType: defaultReviewType as "uncommitted" | "base",
     defaultReviewBranch: defaultReviewBranch as string | undefined,
     runSimplifierByDefault: runSimplifierByDefault as boolean,
-    runWatchByDefault: DEFAULT_CONFIG.run?.watch ?? true,
+    runInteractiveByDefault: DEFAULT_CONFIG.run?.interactive ?? true,
     soundNotificationsEnabled: DEFAULT_CONFIG.notifications?.sound.enabled ?? true,
   } satisfies InitInput;
 }
 
-async function promptForRunWatch(runtime: InitRuntime, defaultValue: boolean): Promise<boolean> {
+async function promptForRunInteractive(
+  runtime: InitRuntime,
+  defaultValue: boolean
+): Promise<boolean> {
   const shouldEnable = await runtime.prompt.confirm({
-    message: "Open Session Panel automatically after 'rr run'?",
+    message: "Launch Interactive Mode automatically after 'rr run'?",
     initialValue: defaultValue,
   });
   handleCancel(runtime, shouldEnable);
@@ -1050,12 +1053,15 @@ export async function runInitWithRuntime(
     setupMode === "auto"
       ? {
           ...resolvedInput,
-          runWatchByDefault: true,
+          runInteractiveByDefault: true,
           soundNotificationsEnabled: true,
         }
       : {
           ...resolvedInput,
-          runWatchByDefault: await promptForRunWatch(runtime, resolvedInput.runWatchByDefault),
+          runInteractiveByDefault: await promptForRunInteractive(
+            runtime,
+            resolvedInput.runInteractiveByDefault
+          ),
           soundNotificationsEnabled: await promptForSoundNotifications(
             runtime,
             resolvedInput.soundNotificationsEnabled

package/src/commands/run.ts

@@ -33,8 +33,8 @@ export interface RunOptions {
   commit?: string;
   custom?: string;
   simplifier?: boolean;
-  watch?: boolean;
-  "no-watch"?: boolean;
+  interactive?: boolean;
+  "no-interactive"?: boolean;
   sound?: boolean;
   "no-sound"?: boolean;
 }
@@ -82,20 +82,20 @@ export function resolveRunSimplifierEnabled(options: RunOptions, config: Config
   return options.simplifier === true || config?.run?.simplifier === true;
 }
 
-export function resolveRunWatchEnabled(options: RunOptions, config: Config | null): boolean {
-  if (options.watch && options["no-watch"]) {
-    throw new Error("Cannot use --watch and --no-watch together");
+export function resolveRunInteractiveEnabled(options: RunOptions, config: Config | null): boolean {
+  if (options.interactive && options["no-interactive"]) {
+    throw new Error("Cannot use --interactive and --no-interactive together");
   }
 
-  if (options.watch) {
+  if (options.interactive) {
     return true;
   }
 
-  if (options["no-watch"]) {
+  if (options["no-interactive"]) {
     return false;
   }
 
-  return config?.run?.watch ?? true;
+  return config?.run?.interactive ?? true;
 }
 
 export function formatRunAgentsNote(config: Config, reviewOptions: ReviewOptions): string {
@@ -377,7 +377,7 @@ async function runInBackground(
     runtime.prompt.log.success(`Review started in background session: ${sessionName}`);
     const reviewOptions: ReviewOptions = { baseBranch, commitSha, customInstructions, simplifier };
     runtime.prompt.note(formatRunAgentsNote(config, reviewOptions), "Agents");
-    runtime.prompt.note("rr status  - Check status\n" + "rr stop    - Stop the review", "Commands");
+    runtime.prompt.note("rr         - Check status\n" + "rr stop    - Stop the review", "Commands");
   } catch (error) {
     await runtime.lockfile.removeLockfile(undefined, projectPath, { expectedSessionId: sessionId });
     runtime.prompt.log.error(`Failed to start background session: ${error}`);
@@ -385,9 +385,9 @@ async function runInBackground(
   }
 }
 
-function logWatchReconnectHint(runtime: RunRuntime): void {
-  runtime.prompt.log.message("Session Panel closed.");
-  runtime.prompt.log.message("Re-open panel: rr status");
+function logInteractiveReconnectHint(runtime: RunRuntime): void {
+  runtime.prompt.log.message("Interactive Mode closed.");
+  runtime.prompt.log.message("Launch Interactive Mode: rr");
   runtime.prompt.log.message("Stop session:   rr stop");
 }
 
@@ -692,17 +692,17 @@ export async function startReview(
   }
 
   const runSimplifier = resolveRunSimplifierEnabled(options, config);
-  let runWatch: boolean;
+  let runInteractive: boolean;
   try {
-    runWatch = resolveRunWatchEnabled(options, config);
+    runInteractive = resolveRunInteractiveEnabled(options, config);
   } catch (error) {
     runtime.prompt.log.error(`${error}`);
     runtime.process.exit(1);
     return;
   }
-  if (runWatch && !runtime.process.stdoutIsTTY) {
-    runtime.prompt.log.warn("Watch mode is disabled because stdout is not a TTY.");
-    runWatch = false;
+  if (runInteractive && !runtime.process.stdoutIsTTY) {
+    runtime.prompt.log.warn("Interactive Mode is disabled because stdout is not a TTY.");
+    runInteractive = false;
   }
 
   // Check if inside tmux - warn about nesting
@@ -722,7 +722,7 @@ export async function startReview(
     soundOverride
   );
 
-  if (!runWatch) {
+  if (!runInteractive) {
     return;
   }
 
@@ -731,8 +731,8 @@ export async function startReview(
     const branch = await runtime.getGitBranch(projectPath);
     await runtime.openSessionPanel(projectPath, branch ?? undefined);
   } catch (error) {
-    runtime.prompt.log.warn(`Could not open Session Panel: ${error}`);
+    runtime.prompt.log.warn(`Could not launch Interactive Mode: ${error}`);
   }
 
-  logWatchReconnectHint(runtime);
+  logInteractiveReconnectHint(runtime);
 }

package/src/commands/stop.ts

@@ -118,7 +118,7 @@ async function stopCurrentSession(): Promise<void> {
     if (allSessions.length > 0) {
       p.log.message(`\nThere are ${allSessions.length} other session(s) running.`);
       p.log.message(
-        'Use "rr stop --all" to stop all running review sessions, or "rr status" to see details.'
+        'Use "rr stop --all" to stop all running review sessions, or "rr" to see details.'
       );
     }
     return;

package/src/commands/update.ts

@@ -15,6 +15,10 @@ interface UpdateRuntime extends SelfUpdateDependencies {
   getCommandDef: (name: string) => CommandDef | undefined;
   parseCommand: typeof parseCommand;
   performSelfUpdate: typeof performSelfUpdate;
+  spinner: () => {
+    start: (message: string) => void;
+    stop: (message: string) => void;
+  };
   log: {
     error: (message: string) => void;
     info: (message: string) => void;
@@ -37,6 +41,7 @@ function createUpdateRuntime(overrides: UpdateRuntimeOverrides = {}): UpdateRunt
     getCommandDef: overrides.getCommandDef ?? getCommandDef,
     parseCommand: overrides.parseCommand ?? parseCommand,
     performSelfUpdate: overrides.performSelfUpdate ?? performSelfUpdate,
+    spinner: overrides.spinner ?? p.spinner,
     log: {
       error: overrides.log?.error ?? p.log.error,
       info: overrides.log?.info ?? p.log.info,
@@ -106,11 +111,14 @@ export async function runUpdate(
     manager: managerValue,
   };
 
+  const spinner = runtime.spinner();
+  spinner.start("Checking for updates...");
   try {
     const result = await runtime.performSelfUpdate(options, runtime);
-
+    spinner.stop("Done.");
     renderSelfUpdateResult(result, runtime);
   } catch (error) {
+    spinner.stop("Update failed.");
     if (error instanceof SelfUpdateError) {
       runtime.log.error(error.message);
       for (const note of error.notes) {

package/src/lib/cli-parser.ts

@@ -108,6 +108,11 @@ export interface ParseResult<T = Record<string, unknown>> {
   positional: string[];
 }
 
+interface UsageEntry {
+  command: string;
+  description: string;
+}
+
 function buildOptionMaps(options: OptionDef[]): {
   byName: Map<string, OptionDef>;
   byAlias: Map<string, OptionDef>;
@@ -359,31 +364,46 @@ export function formatCommandHelp(def: CommandDef): string {
   return lines.join("\n");
 }
 
+function getCommandDisplayName(command: CommandDef): string {
+  if (command.aliases?.length) {
+    return `${command.name} (${command.aliases.join(", ")})`;
+  }
+
+  return command.name;
+}
+
 export function formatMainHelp(commands: CommandDef[], version: string): string {
   const lines: string[] = [];
+  const usageEntries: UsageEntry[] = [
+    { command: "rr", description: "Launch Interactive Mode" },
+    { command: "rr", description: "<command> [options]" },
+    { command: "rrr", description: "Quick alias for 'rr run'" },
+  ];
 
   lines.push(
     `${theme.accent("ralph-review")} v${theme.muted(version)} - ${theme.info("Ralph Wiggum Code Review Orchestrator")}`
   );
   lines.push("");
   lines.push(`${theme.heading("USAGE:")}`);
-  lines.push(`  ${theme.command("rr")} <command> [options]`);
-  lines.push(`  ${theme.command("rrr")}           Quick alias for 'rr run'`);
+  const maxUsageCommandLen = Math.max(...usageEntries.map((entry) => entry.command.length));
+  for (const entry of usageEntries) {
+    const padding = " ".repeat(maxUsageCommandLen - entry.command.length + 2);
+    lines.push(`  ${theme.command(entry.command)}${padding}${entry.description}`);
+  }
   lines.push("");
   lines.push(`${theme.heading("COMMANDS:")}`);
 
   const publicCommands = commands.filter((c) => !c.hidden);
 
-  // Calculate max display name length (including aliases like "list (ls)")
-  const getDisplayName = (cmd: CommandDef): string =>
-    cmd.aliases?.length ? `${cmd.name} (${cmd.aliases.join(", ")})` : cmd.name;
-  const maxNameLen = Math.max(...publicCommands.map((c) => getDisplayName(c).length));
+  const maxNameLen = Math.max(
+    ...publicCommands.map((command) => getCommandDisplayName(command).length)
+  );
 
-  for (const cmd of publicCommands) {
-    const displayName = getDisplayName(cmd);
+  for (const command of publicCommands) {
+    const displayName = getCommandDisplayName(command);
     const coloredName = theme.command(displayName);
     const paddedName = coloredName + " ".repeat(maxNameLen - displayName.length + 2);
-    lines.push(`  ${paddedName}${cmd.description}`);
+    lines.push(`  ${paddedName}${command.description}`);
   }
 
   lines.push("");

package/src/lib/config.ts

@@ -18,6 +18,19 @@ import {
 const CONFIG_DIR = join(homedir(), ".config", "ralph-review");
 export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
 export const LOGS_DIR = join(CONFIG_DIR, "logs");
+const VALID_AGENT_VALUES = ["codex", "claude", "opencode", "droid", "gemini", "pi"] as const;
+const VALID_AGENT_CHOICES = VALID_AGENT_VALUES.join(", ");
+const VALID_REASONING_VALUES = ["low", "medium", "high", "xhigh", "max"] as const;
+const RUN_SETTING_KEYS = ["simplifier", "interactive"] as const;
+
+export interface ConfigParseDiagnostics {
+  config: Config | null;
+  errors: string[];
+}
+
+export interface LoadedConfigDiagnostics extends ConfigParseDiagnostics {
+  exists: boolean;
+}
 
 function withCanonicalMetadata(
   config: Omit<Config, "$schema" | "version"> & Partial<Pick<Config, "$schema" | "version">>
@@ -46,39 +59,67 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
 
-function parseRetryConfig(value: unknown): RetryConfig | undefined {
+function parseRetryConfigWithDiagnostics(
+  value: unknown,
+  errors: string[]
+): RetryConfig | undefined {
   if (value === undefined) {
     return undefined;
   }
   if (!isRecord(value)) {
+    errors.push("retry must be an object.");
     return undefined;
   }
 
   const maxRetries = value.maxRetries;
   const baseDelayMs = value.baseDelayMs;
   const maxDelayMs = value.maxDelayMs;
+  let hasError = false;
+
+  if (typeof maxRetries !== "number") {
+    errors.push("retry.maxRetries must be a number.");
+    hasError = true;
+  }
+  if (typeof baseDelayMs !== "number") {
+    errors.push("retry.baseDelayMs must be a number.");
+    hasError = true;
+  }
+  if (typeof maxDelayMs !== "number") {
+    errors.push("retry.maxDelayMs must be a number.");
+    hasError = true;
+  }
 
   if (
-    typeof maxRetries !== "number" ||
-    typeof baseDelayMs !== "number" ||
-    typeof maxDelayMs !== "number"
+    !hasError &&
+    typeof maxRetries === "number" &&
+    typeof baseDelayMs === "number" &&
+    typeof maxDelayMs === "number"
   ) {
-    return undefined;
+    return { maxRetries, baseDelayMs, maxDelayMs };
   }
 
-  return { maxRetries, baseDelayMs, maxDelayMs };
+  return undefined;
 }
 
-function parseNotificationsConfig(value: unknown): NotificationsConfig | undefined {
+function parseNotificationsConfigWithDiagnostics(
+  value: unknown,
+  errors: string[]
+): NotificationsConfig | undefined {
   if (value === undefined) {
     return undefined;
   }
   if (!isRecord(value)) {
+    errors.push("notifications must be an object.");
     return undefined;
   }
 
   const sound = value.sound;
-  if (!isRecord(sound) || typeof sound.enabled !== "boolean") {
+  if (!isRecord(sound)) {
+    errors.push("notifications.sound must be an object.");
+    return undefined;
+  }
+  if (typeof sound.enabled !== "boolean") {
+    errors.push("notifications.sound.enabled must be a boolean.");
     return undefined;
   }
 
@@ -89,29 +130,60 @@ function parseNotificationsConfig(value: unknown): NotificationsConfig | undefin
   };
 }
 
-function parseRunConfig(value: unknown): RunConfig | undefined {
+function formatRunSettingChoices(): string {
+  return RUN_SETTING_KEYS.map((key) => `run.${key}`).join(", ");
+}
+
+function parseRunConfigWithDiagnostics(value: unknown, errors: string[]): RunConfig | undefined {
   if (value === undefined) {
     return undefined;
   }
   if (!isRecord(value)) {
+    errors.push("run must be an object.");
     return undefined;
   }
 
-  if (typeof value.simplifier !== "boolean") {
-    return undefined;
+  const keys = Object.keys(value);
+  let hasError = false;
+  for (const key of keys) {
+    if (key === "simplifier" || key === "interactive") {
+      continue;
+    }
+
+    errors.push(`run.${key} is not supported. Available settings: ${formatRunSettingChoices()}.`);
+    hasError = true;
   }
-  if (value.watch !== undefined && typeof value.watch !== "boolean") {
-    return undefined;
+
+  const simplifier = value.simplifier;
+  const interactive = value.interactive === undefined ? true : value.interactive;
+
+  if (typeof simplifier !== "boolean") {
+    errors.push("run.simplifier must be a boolean.");
+    hasError = true;
+  }
+  if (typeof interactive !== "boolean") {
+    errors.push("run.interactive must be a boolean.");
+    hasError = true;
   }
 
-  return {
-    simplifier: value.simplifier,
-    watch: value.watch === undefined ? true : value.watch,
-  };
+  if (!hasError && typeof simplifier === "boolean" && typeof interactive === "boolean") {
+    return {
+      simplifier,
+      interactive,
+    };
+  }
+
+  return undefined;
 }
 
-function parseDefaultReview(value: unknown): DefaultReview | null {
-  if (!isRecord(value) || typeof value.type !== "string") {
+function parseDefaultReviewWithDiagnostics(value: unknown, errors: string[]): DefaultReview | null {
+  if (!isRecord(value)) {
+    errors.push('defaultReview must be an object with type "uncommitted" or "base".');
+    return null;
+  }
+
+  if (typeof value.type !== "string") {
+    errors.push('defaultReview.type must be "uncommitted" or "base".');
     return null;
   }
 
@@ -123,112 +195,197 @@ function parseDefaultReview(value: unknown): DefaultReview | null {
     return { type: "base", branch: value.branch };
   }
 
+  if (value.type === "base") {
+    errors.push(
+      'defaultReview.branch must be a non-empty string when defaultReview.type is "base".'
+    );
+    return null;
+  }
+
+  errors.push('defaultReview.type must be "uncommitted" or "base".');
   return null;
 }
 
-function parseAgentSettings(value: unknown): AgentSettings | null {
+function parseAgentSettingsWithDiagnostics(
+  value: unknown,
+  path: "reviewer" | "fixer" | "code-simplifier",
+  errors: string[]
+): AgentSettings | null {
   if (!isRecord(value)) {
+    errors.push(`${path} must be an object.`);
     return null;
   }
 
-  if (!isAgentType(value.agent)) {
-    return null;
+  const agent = isAgentType(value.agent) ? value.agent : undefined;
+  let reasoning: AgentSettings["reasoning"] | undefined;
+  if (value.reasoning !== undefined) {
+    reasoning = isReasoningLevel(value.reasoning) ? value.reasoning : undefined;
   }
+  let hasError = false;
 
-  if (value.reasoning !== undefined && !isReasoningLevel(value.reasoning)) {
-    return null;
+  if (!agent) {
+    hasError = true;
+    errors.push(`${path}.agent must be one of: ${VALID_AGENT_CHOICES}.`);
+  }
+  if (value.reasoning !== undefined && reasoning === undefined) {
+    errors.push(`${path}.reasoning must be one of: ${VALID_REASONING_VALUES.join(", ")}.`);
+    hasError = true;
   }
 
-  if (value.agent === "pi") {
-    if (typeof value.provider !== "string" || typeof value.model !== "string") {
-      return null;
+  if (agent === "pi") {
+    const provider = value.provider;
+    const model = value.model;
+
+    if (typeof provider !== "string") {
+      errors.push(`${path}.provider must be a string when ${path}.agent is "pi".`);
+      hasError = true;
+    }
+    if (typeof model !== "string") {
+      errors.push(`${path}.model must be a string when ${path}.agent is "pi".`);
+      hasError = true;
     }
 
-    return {
-      agent: "pi",
-      provider: value.provider,
-      model: value.model,
-      reasoning: value.reasoning,
-    };
-  }
+    if (!hasError && typeof provider === "string" && typeof model === "string") {
+      return {
+        agent: "pi",
+        provider,
+        model,
+        reasoning,
+      };
+    }
 
-  if (value.provider !== undefined) {
     return null;
   }
+
+  if (agent && value.provider !== undefined) {
+    errors.push(`${path}.provider is only valid when ${path}.agent is "pi".`);
+    hasError = true;
+  }
   if (value.model !== undefined && typeof value.model !== "string") {
+    errors.push(`${path}.model must be a string.`);
+    hasError = true;
+  }
+
+  if (!agent || hasError) {
     return null;
   }
 
   return {
-    agent: value.agent,
-    model: value.model,
-    reasoning: value.reasoning,
+    agent,
+    model: typeof value.model === "string" ? value.model : undefined,
+    reasoning,
   };
 }
 
-export function parseConfig(value: unknown): Config | null {
+function uniqueErrors(errors: string[]): string[] {
+  return [...new Set(errors)];
+}
+
+export function parseConfigWithDiagnostics(value: unknown): ConfigParseDiagnostics {
   if (!isRecord(value)) {
-    return null;
+    return {
+      config: null,
+      errors: ["Configuration must be a JSON object."],
+    };
   }
 
-  const reviewer = parseAgentSettings(value.reviewer);
-  const fixer = parseAgentSettings(value.fixer);
-  const codeSimplifier = parseAgentSettings(value["code-simplifier"]);
-  const defaultReview = parseDefaultReview(value.defaultReview);
-  const retry = parseRetryConfig(value.retry);
-  const notifications = parseNotificationsConfig(value.notifications);
-  const run = parseRunConfig(value.run);
-
-  if (!reviewer || !fixer || !defaultReview) {
-    return null;
+  const errors: string[] = [];
+  const reviewer = parseAgentSettingsWithDiagnostics(value.reviewer, "reviewer", errors);
+  const fixer = parseAgentSettingsWithDiagnostics(value.fixer, "fixer", errors);
+  const codeSimplifier =
+    value["code-simplifier"] === undefined
+      ? undefined
+      : parseAgentSettingsWithDiagnostics(value["code-simplifier"], "code-simplifier", errors);
+  const defaultReview = parseDefaultReviewWithDiagnostics(value.defaultReview, errors);
+  const retry = parseRetryConfigWithDiagnostics(value.retry, errors);
+  const notifications = parseNotificationsConfigWithDiagnostics(value.notifications, errors);
+  const run = parseRunConfigWithDiagnostics(value.run, errors);
+  const maxIterations = typeof value.maxIterations === "number" ? value.maxIterations : undefined;
+  const iterationTimeout =
+    typeof value.iterationTimeout === "number" ? value.iterationTimeout : undefined;
+
+  if (maxIterations === undefined) {
+    errors.push("maxIterations must be a number.");
   }
-  if (value["code-simplifier"] !== undefined && !codeSimplifier) {
-    return null;
-  }
-  if (value.retry !== undefined && !retry) {
-    return null;
-  }
-  if (value.notifications !== undefined && !notifications) {
-    return null;
+  if (iterationTimeout === undefined) {
+    errors.push("iterationTimeout must be a number.");
   }
-  if (value.run !== undefined && !run) {
-    return null;
-  }
-  if (typeof value.maxIterations !== "number" || typeof value.iterationTimeout !== "number") {
-    return null;
+
+  if (
+    !reviewer ||
+    !fixer ||
+    !defaultReview ||
+    maxIterations === undefined ||
+    iterationTimeout === undefined ||
+    errors.length > 0 ||
+    (value["code-simplifier"] !== undefined && !codeSimplifier) ||
+    (value.retry !== undefined && !retry) ||
+    (value.notifications !== undefined && !notifications) ||
+    (value.run !== undefined && !run)
+  ) {
+    return {
+      config: null,
+      errors: uniqueErrors(errors),
+    };
   }
 
-  return withCanonicalMetadata({
-    reviewer,
-    fixer,
-    ...(codeSimplifier ? { "code-simplifier": codeSimplifier } : {}),
-    ...(run ? { run } : {}),
-    maxIterations: value.maxIterations,
-    iterationTimeout: value.iterationTimeout,
-    ...(retry ? { retry } : {}),
-    defaultReview,
-    notifications: notifications ?? {
-      sound: { enabled: DEFAULT_NOTIFICATIONS_CONFIG.sound.enabled },
-    },
-  });
+  return {
+    config: withCanonicalMetadata({
+      reviewer,
+      fixer,
+      ...(codeSimplifier ? { "code-simplifier": codeSimplifier } : {}),
+      ...(run ? { run } : {}),
+      maxIterations,
+      iterationTimeout,
+      ...(retry ? { retry } : {}),
+      defaultReview,
+      notifications: notifications ?? {
+        sound: { enabled: DEFAULT_NOTIFICATIONS_CONFIG.sound.enabled },
+      },
+    }),
+    errors: [],
+  };
 }
 
-export async function loadConfig(path: string = CONFIG_PATH): Promise<Config | null> {
+export function parseConfig(value: unknown): Config | null {
+  return parseConfigWithDiagnostics(value).config;
+}
+
+export async function loadConfigWithDiagnostics(
+  path: string = CONFIG_PATH
+): Promise<LoadedConfigDiagnostics> {
   const file = Bun.file(path);
 
   if (!(await file.exists())) {
-    return null;
+    return {
+      exists: false,
+      config: null,
+      errors: [],
+    };
   }
 
   try {
     const content = await file.text();
     const parsed = JSON.parse(content) as unknown;
-    return parseConfig(parsed);
-  } catch {
-    return null;
+    const result = parseConfigWithDiagnostics(parsed);
+    return {
+      exists: true,
+      ...result,
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      config: null,
+      errors: [`Invalid JSON syntax: ${error instanceof Error ? error.message : String(error)}`],
+    };
   }
 }
 
+export async function loadConfig(path: string = CONFIG_PATH): Promise<Config | null> {
+  const loaded = await loadConfigWithDiagnostics(path);
+  return loaded.config;
+}
+
 export async function configExists(path: string = CONFIG_PATH): Promise<boolean> {
   return await Bun.file(path).exists();
 }
@@ -236,6 +393,6 @@ export async function configExists(path: string = CONFIG_PATH): Promise<boolean>
 export const DEFAULT_CONFIG: Partial<Config> = {
   maxIterations: 5,
   iterationTimeout: 1800000,
-  run: { simplifier: false, watch: true },
+  run: { simplifier: false, interactive: true },
   notifications: { sound: { enabled: DEFAULT_NOTIFICATIONS_CONFIG.sound.enabled } },
 };

package/src/lib/diagnostics/checks.ts

@@ -558,7 +558,7 @@ export async function runDiagnostics(
           ? "A review is already running for this project."
           : "No running review lock detected.",
         remediation: hasRunningReview
-          ? [runStep("rr status"), runStep("rr stop"), thenStep("rr run")]
+          ? [runStep("rr"), runStep("rr stop"), thenStep("rr run")]
           : [],
         fixable: hasRunningReview && isFixable("run-lockfile"),
       });

package/src/lib/diagnostics/remediation.ts

@@ -143,7 +143,7 @@ async function fixConfig(id: string, deps: RemediationDependencies): Promise<Fix
   }
 }
 
-const LOCKFILE_FIX_NEXT_ACTIONS = ["Run: rr status", "Run: rr stop", "Then run: rr run"];
+const LOCKFILE_FIX_NEXT_ACTIONS = ["Run: rr", "Run: rr stop", "Then run: rr run"];
 
 async function fixLockfile(deps: RemediationDependencies): Promise<FixResult> {
   try {

package/src/lib/self-update.ts

@@ -50,6 +50,7 @@ const BREW_INSTALLED_VERSION_ERROR =
   "Could not determine the installed Homebrew version for ralph-review.";
 const BREW_LATEST_VERSION_ERROR =
   "Could not determine the latest Homebrew version for ralph-review.";
+const BREW_UPDATE_ERROR = "Failed to refresh Homebrew metadata for ralph-review.";
 const NPM_INSTALLED_VERSION_ERROR =
   "Could not determine the installed npm version for ralph-review.";
 const VERSION_COMPARE_ERROR =
@@ -474,6 +475,10 @@ async function getBrewVersions(
   return parseBrewVersions(output);
 }
 
+async function refreshBrewMetadata(deps: SelfUpdateDependencies): Promise<void> {
+  await readTextOutput(deps, ["brew", "update", "--quiet"], BREW_UPDATE_ERROR);
+}
+
 async function performNpmSelfUpdate(
   options: SelfUpdateOptions,
   deps: SelfUpdateDependencies
@@ -521,6 +526,7 @@ async function performBrewSelfUpdate(
   deps: SelfUpdateDependencies
 ): Promise<SelfUpdateResult> {
   ensureManagerAvailable("brew", deps);
+  await refreshBrewMetadata(deps);
 
   const { currentVersion, latestVersion } = await getBrewVersions(deps);
   if (!hasNewerVersion(currentVersion, latestVersion)) {

package/src/lib/tui/components/StatusBar.tsx

@@ -19,18 +19,18 @@ export function StatusBar({ hasSession, focusedPanel }: StatusBarProps) {
       <box flexDirection="row" gap={2}>
         <text>
           <span fg={TUI_COLORS.accent.key}>[q]</span>
-          <span fg={TUI_COLORS.text.muted}> Close panel</span>
+          <span fg={TUI_COLORS.text.muted}> Quit</span>
         </text>
         {!hasSession && (
           <text>
             <span fg={TUI_COLORS.accent.key}>[r]</span>
-            <span fg={TUI_COLORS.text.muted}> Run</span>
+            <span fg={TUI_COLORS.text.muted}> Run Review</span>
           </text>
         )}
         {hasSession && (
           <text>
             <span fg={TUI_COLORS.accent.key}>[s]</span>
-            <span fg={TUI_COLORS.text.muted}> Stop</span>
+            <span fg={TUI_COLORS.text.muted}> Stop Review</span>
           </text>
         )}
         <text>

package/src/lib/types/config.ts

@@ -44,7 +44,7 @@ export interface NotificationsConfig {
 
 export interface RunConfig {
   simplifier: boolean;
-  watch: boolean;
+  interactive: boolean;
 }
 
 export const CONFIG_SCHEMA_URI =