ralph-cli-sandboxed 0.2.0 → 0.2.2

package/README.md

@@ -71,6 +71,20 @@ After running `ralph init`, you'll have:
 - **Rust** - `cargo check`, `cargo test`
 - **Custom** - Define your own commands
 
+### Supported CLI Providers
+
+Ralph supports multiple AI CLI tools. Select your provider during `ralph init`:
+
+| CLI | Status | Environment Variables | Notes |
+|-----|--------|----------------------|-------|
+| [Claude Code](https://github.com/anthropics/claude-code) | Working | `ANTHROPIC_API_KEY` | Default provider. Also supports ~/.claude OAuth credentials |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Working | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | |
+| [OpenCode](https://github.com/anomalyco/opencode) | Working | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` | Requires [PR #9073](https://github.com/anomalyco/opencode/pull/9073) |
+| [Aider](https://github.com/paul-gauthier/aider) | Untested | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | |
+| [Codex CLI](https://github.com/openai/codex) | Untested | `OPENAI_API_KEY` | |
+| [AMP](https://ampcode.com/) | Untested | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | |
+| Custom | - | User-defined | Configure your own CLI |
+
 ### CLI Configuration
 
 Ralph can be configured to use different AI CLI tools. By default, it uses Claude Code. Configure in `.ralph/config.json`:
@@ -221,8 +235,8 @@ podman run -v $(pwd):/workspace -v /workspace/node_modules your-image
 ## Requirements
 
 - Node.js 18+
-- [Claude Code CLI](https://github.com/anthropics/claude-code) installed
-- Claude Pro/Max subscription or Anthropic API key
+- A supported AI CLI tool installed (see [Supported CLI Providers](#supported-cli-providers))
+- API key or subscription for your chosen provider
 
 ## License
 

package/dist/commands/docker.js

@@ -29,7 +29,7 @@ function getCliProviderSnippet(cliProvider) {
     const provider = cliProvidersJson.providers[providerKey];
     if (!provider || !provider.docker) {
         // Default to Claude Code CLI if provider not found
-        return "# Install Claude Code CLI\nRUN curl -fsSL https://claude.ai/install.sh | bash";
+        return "# Install Claude Code CLI (as node user so it installs to /home/node/.local/bin)\nRUN su - node -c 'curl -fsSL https://claude.ai/install.sh | bash' \\\n    && echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> /home/node/.zshrc";
     }
     return provider.docker.install;
 }
@@ -291,9 +291,13 @@ async function buildImage(ralphDir) {
         process.exit(1);
     }
     console.log("Building Docker image...\n");
+    // Get image name for compose project name
+    const config = loadConfig();
+    const imageName = config.imageName || `ralph-${basename(process.cwd()).toLowerCase().replace(/[^a-z0-9-]/g, "-")}`;
     return new Promise((resolve, reject) => {
         // Use --no-cache and --pull to ensure we always get the latest CLI versions
-        const proc = spawn("docker", ["compose", "build", "--no-cache", "--pull"], {
+        // Use -p to set unique project name per ralph project
+        const proc = spawn("docker", ["compose", "-p", imageName, "build", "--no-cache", "--pull"], {
             cwd: dockerDir,
             stdio: "inherit",
         });
@@ -329,6 +333,27 @@ async function imageExists(imageName) {
         });
     });
 }
+// Get CLI provider configuration
+function getCliProviderConfig(cliProvider) {
+    const cliProvidersJson = getCliProvidersJson();
+    const providerKey = cliProvider || "claude";
+    const provider = cliProvidersJson.providers[providerKey];
+    if (!provider) {
+        // Default to Claude Code CLI if provider not found
+        return {
+            name: "Claude Code",
+            command: "claude",
+            yoloArgs: ["--dangerously-skip-permissions"],
+            envVars: ["ANTHROPIC_API_KEY"],
+        };
+    }
+    return {
+        name: provider.name,
+        command: provider.command,
+        yoloArgs: provider.yoloArgs || [],
+        envVars: provider.envVars || [],
+    };
+}
 async function runContainer(ralphDir, imageName, language, javaVersion, cliProvider) {
     const dockerDir = join(ralphDir, DOCKER_DIR);
     const dockerfileExists = existsSync(join(dockerDir, "Dockerfile"));
@@ -346,9 +371,37 @@ async function runContainer(ralphDir, imageName, language, javaVersion, cliProvi
             console.log("");
         }
     }
+    // Get CLI provider info for the startup note
+    const cliConfig = getCliProviderConfig(cliProvider);
+    const yoloCommand = cliConfig.yoloArgs.length > 0
+        ? `${cliConfig.command} ${cliConfig.yoloArgs.join(" ")}`
+        : cliConfig.command;
     console.log("Starting Docker container...\n");
+    // Show note about yolo mode and credentials
+    console.log("IMPORTANT: Getting Started");
+    console.log("-".repeat(40));
+    console.log("");
+    console.log("To run ralph automation, you might need to activate YOLO mode");
+    console.log("which allows the AI to execute commands without prompts.");
+    console.log("");
+    console.log(`CLI Provider: ${cliConfig.name}`);
+    console.log(`Yolo command: ${yoloCommand}`);
+    console.log("");
+    console.log("Before running 'ralph run' or 'ralph once', ensure your");
+    console.log("credentials are configured:");
+    console.log("");
+    if (cliConfig.envVars.length > 0) {
+        console.log("Required environment variables:");
+        for (const envVar of cliConfig.envVars) {
+            console.log(`  - ${envVar}`);
+        }
+    }
+    console.log("");
+    console.log("Set them in docker-compose.yml or export before running.");
+    console.log("");
     return new Promise((resolve, reject) => {
-        const proc = spawn("docker", ["compose", "run", "--rm", "ralph"], {
+        // Use -p to set unique project name per ralph project
+        const proc = spawn("docker", ["compose", "-p", imageName, "run", "--rm", "ralph"], {
             cwd: dockerDir,
             stdio: "inherit",
         });
@@ -371,8 +424,9 @@ async function cleanImage(imageName, ralphDir) {
     // First, stop any running containers via docker compose
     if (existsSync(join(dockerDir, "docker-compose.yml"))) {
         // Stop running containers first
+        // Use -p to target only this project's resources
         await new Promise((resolve) => {
-            const proc = spawn("docker", ["compose", "stop", "--timeout", "5"], {
+            const proc = spawn("docker", ["compose", "-p", imageName, "stop", "--timeout", "5"], {
                 cwd: dockerDir,
                 stdio: "inherit",
             });
@@ -384,8 +438,9 @@ async function cleanImage(imageName, ralphDir) {
             });
         });
         // Remove containers, volumes, networks, and local images
+        // Use -p to target only this project's resources
         await new Promise((resolve) => {
-            const proc = spawn("docker", ["compose", "down", "--rmi", "local", "-v", "--remove-orphans", "--timeout", "5"], {
+            const proc = spawn("docker", ["compose", "-p", imageName, "down", "--rmi", "local", "-v", "--remove-orphans", "--timeout", "5"], {
                 cwd: dockerDir,
                 stdio: "inherit",
             });
@@ -398,9 +453,10 @@ async function cleanImage(imageName, ralphDir) {
             });
         });
     }
-    // Find and forcibly remove any containers using volumes with our image name pattern
+    // Find and forcibly remove any containers using volumes with our project name pattern
     // This handles orphaned containers from previous runs or pods
-    const volumePattern = `docker_${imageName}`;
+    // Project name is now imageName (via -p flag), so volumes are named ${imageName}_*
+    const volumePattern = imageName;
     await new Promise((resolve) => {
         // List all containers (including stopped) and filter by volume name pattern
         const proc = spawn("docker", ["ps", "-aq", "--filter", `volume=${volumePattern}`], {
@@ -510,8 +566,8 @@ async function cleanImage(imageName, ralphDir) {
             resolve();
         });
     });
-    // Clean up project-specific network (named after imageName, not generic docker_default)
-    const networkName = `docker_${imageName}_default`;
+    // Clean up project-specific network (project name is imageName via -p flag)
+    const networkName = `${imageName}_default`;
     await new Promise((resolve) => {
         const proc = spawn("docker", ["network", "rm", networkName], {
             stdio: ["ignore", "ignore", "ignore"], // Suppress output - network may not exist

package/dist/commands/init.js

@@ -45,10 +45,13 @@ export async function init(_args) {
         const customArgs = customArgsInput.trim() ? customArgsInput.trim().split(/\s+/) : [];
         const customYoloArgsInput = await promptInput("Enter yolo/auto-approve arguments (space-separated): ");
         const customYoloArgs = customYoloArgsInput.trim() ? customYoloArgsInput.trim().split(/\s+/) : [];
+        const customPromptArgsInput = await promptInput("Enter prompt arguments (e.g., -p for flag-based, leave empty for positional): ");
+        const customPromptArgs = customPromptArgsInput.trim() ? customPromptArgsInput.trim().split(/\s+/) : [];
         cliConfig = {
             command: customCommand || "claude",
             args: customArgs,
             yoloArgs: customYoloArgs.length > 0 ? customYoloArgs : undefined,
+            promptArgs: customPromptArgs,
         };
     }
     else {
@@ -56,6 +59,7 @@ export async function init(_args) {
             command: selectedProvider.command,
             args: selectedProvider.defaultArgs,
             yoloArgs: selectedProvider.yoloArgs.length > 0 ? selectedProvider.yoloArgs : undefined,
+            promptArgs: selectedProvider.promptArgs ?? [],
         };
     }
     console.log(`\nSelected CLI provider: ${CLI_PROVIDERS[selectedCliProviderKey].name}`);

package/dist/commands/once.d.ts

@@ -1 +1 @@
-export declare function once(_args: string[]): Promise<void>;
+export declare function once(args: string[]): Promise<void>;

package/dist/commands/once.js

@@ -1,7 +1,8 @@
 import { spawn } from "child_process";
 import { checkFilesExist, loadConfig, loadPrompt, getPaths, getCliConfig, requireContainer } from "../utils/config.js";
 import { resolvePromptVariables } from "../templates/prompts.js";
-export async function once(_args) {
+export async function once(args) {
+    const debug = args.includes("--debug") || args.includes("-d");
     requireContainer("once");
     checkFilesExist();
     const config = loadConfig();
@@ -18,16 +19,20 @@ export async function once(_args) {
     // Build CLI arguments: config args + yolo args + prompt args
     // Use yoloArgs from config if available, otherwise default to Claude's --dangerously-skip-permissions
     const yoloArgs = cliConfig.yoloArgs ?? ["--dangerously-skip-permissions"];
+    const promptArgs = cliConfig.promptArgs ?? ["-p"];
+    const promptValue = `@${paths.prd} @${paths.progress} ${prompt}`;
     const cliArgs = [
         ...(cliConfig.args ?? []),
         ...yoloArgs,
-        "-p",
-        `@${paths.prd} @${paths.progress} ${prompt}`,
+        ...promptArgs,
+        promptValue,
     ];
+    if (debug) {
+        console.log(`[debug] ${cliConfig.command} ${cliArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}\n`);
+    }
     return new Promise((resolve, reject) => {
         const proc = spawn(cliConfig.command, cliArgs, {
             stdio: "inherit",
-            shell: true,
         });
         proc.on("close", (code) => {
             if (code !== 0) {

package/dist/commands/prd.js

@@ -216,10 +216,10 @@ export function parseListArgs(args) {
                 process.exit(1);
             }
         }
-        else if (args[i] === "--passes") {
+        else if (args[i] === "--passes" || args[i] === "--passed") {
             passesFilter = true;
         }
-        else if (args[i] === "--no-passes") {
+        else if (args[i] === "--no-passes" || args[i] === "--no-passed" || args[i] === "--not-passed" || args[i] === "--not-passes") {
             passesFilter = false;
         }
     }

package/dist/commands/run.js

@@ -25,7 +25,7 @@ function createFilteredPrd(prdPath, category) {
         hasIncomplete: filteredItems.length > 0
     };
 }
-async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig) {
+async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug) {
     return new Promise((resolve, reject) => {
         let output = "";
         // Build CLI arguments: config args + yolo args + prompt args
@@ -39,7 +39,13 @@ async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig
             cliArgs.push(...yoloArgs);
         }
         // Use the filtered PRD (only incomplete items) for the prompt
-        cliArgs.push("-p", `@${filteredPrdPath} @${paths.progress} ${prompt}`);
+        // promptArgs specifies flags to use (e.g., ["-p"] for Claude, [] for positional)
+        const promptArgs = cliConfig.promptArgs ?? ["-p"];
+        const promptValue = `@${filteredPrdPath} @${paths.progress} ${prompt}`;
+        cliArgs.push(...promptArgs, promptValue);
+        if (debug) {
+            console.log(`[debug] ${cliConfig.command} ${cliArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}\n`);
+        }
         const proc = spawn(cliConfig.command, cliArgs, {
             stdio: ["inherit", "pipe", "inherit"],
         });
@@ -104,6 +110,7 @@ export async function run(args) {
     let category;
     let loopMode = false;
     let allModeExplicit = false;
+    let debug = false;
     const filteredArgs = [];
     for (let i = 0; i < args.length; i++) {
         if (args[i] === "--category" || args[i] === "-c") {
@@ -123,6 +130,9 @@ export async function run(args) {
         else if (args[i] === "--all" || args[i] === "-a") {
             allModeExplicit = true;
         }
+        else if (args[i] === "--debug" || args[i] === "-d") {
+            debug = true;
+        }
         else {
             filteredArgs.push(args[i]);
         }
@@ -173,7 +183,10 @@ export async function run(args) {
     // Track temp file for cleanup
     let filteredPrdPath = null;
     const POLL_INTERVAL_MS = 30000; // 30 seconds between checks when waiting for new items
+    const MAX_CONSECUTIVE_FAILURES = 3; // Stop after this many consecutive failures
     const startTime = Date.now();
+    let consecutiveFailures = 0;
+    let lastExitCode = 0;
     try {
         for (let i = 1; i <= iterations; i++) {
             console.log(`\n${"=".repeat(50)}`);
@@ -246,7 +259,7 @@ export async function run(args) {
                     break;
                 }
             }
-            const { exitCode, output } = await runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig);
+            const { exitCode, output } = await runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug);
             // Clean up temp file after each iteration
             try {
                 unlinkSync(filteredPrdPath);
@@ -257,8 +270,27 @@ export async function run(args) {
             filteredPrdPath = null;
             if (exitCode !== 0) {
                 console.error(`\n${cliConfig.command} exited with code ${exitCode}`);
+                // Track consecutive failures to detect persistent errors (e.g., missing API key)
+                if (exitCode === lastExitCode) {
+                    consecutiveFailures++;
+                }
+                else {
+                    consecutiveFailures = 1;
+                    lastExitCode = exitCode;
+                }
+                if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+                    console.error(`\nStopping: ${cliConfig.command} failed ${consecutiveFailures} times in a row with exit code ${exitCode}.`);
+                    console.error("This usually indicates a configuration error (e.g., missing API key).");
+                    console.error("Please check your CLI configuration and try again.");
+                    break;
+                }
                 console.log("Continuing to next iteration...");
             }
+            else {
+                // Reset failure tracking on success
+                consecutiveFailures = 0;
+                lastExitCode = 0;
+            }
             // Check for completion signal
             if (output.includes("<promise>COMPLETE</promise>")) {
                 if (loopMode) {

package/dist/config/cli-providers.json

@@ -6,8 +6,9 @@
       "command": "claude",
       "defaultArgs": ["--permission-mode", "acceptEdits"],
       "yoloArgs": ["--dangerously-skip-permissions"],
+      "promptArgs": ["-p"],
       "docker": {
-        "install": "# Install Claude Code CLI\nRUN curl -fsSL https://claude.ai/install.sh | bash"
+        "install": "# Install Claude Code CLI (as node user so it installs to /home/node/.local/bin)\nRUN su - node -c 'curl -fsSL https://claude.ai/install.sh | bash' \\\n    && echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> /home/node/.zshrc"
       },
       "envVars": ["ANTHROPIC_API_KEY"],
       "credentialMount": "~/.claude:/home/node/.claude"
@@ -18,6 +19,7 @@
       "command": "aider",
       "defaultArgs": ["--yes"],
       "yoloArgs": ["--yes-always"],
+      "promptArgs": ["--message"],
       "docker": {
         "install": "# Install Aider (requires Python)\nRUN apt-get update && apt-get install -y python3 python3-pip && rm -rf /var/lib/apt/lists/* \\\n    && pip3 install --break-system-packages --no-cache-dir aider-chat",
         "note": "Check 'aider --help' for available flags"
@@ -31,6 +33,7 @@
       "command": "codex",
       "defaultArgs": ["--approval-mode", "suggest"],
       "yoloArgs": ["--approval-mode", "full-auto"],
+      "promptArgs": [],
       "docker": {
         "install": "# Install OpenAI Codex CLI\nRUN npm install -g @openai/codex",
         "note": "Check 'codex --help' for available flags"
@@ -44,11 +47,12 @@
       "command": "gemini",
       "defaultArgs": [],
       "yoloArgs": ["-y"],
+      "promptArgs": [],
       "docker": {
         "install": "# Install Google Gemini CLI\nRUN npm install -g @google/gemini-cli",
         "note": "Check 'gemini --help' for available flags"
       },
-      "envVars": ["GOOGLE_API_KEY", "GEMINI_API_KEY"],
+      "envVars": ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
       "credentialMount": "~/.gemini:/home/node/.gemini"
     },
     "opencode": {
@@ -57,11 +61,12 @@
       "command": "opencode",
       "defaultArgs": [],
       "yoloArgs": ["--yolo"],
+      "promptArgs": ["run"],
       "docker": {
-        "install": "# Install OpenCode\nRUN curl -fsSL https://opencode.ai/install | bash \\\n    && echo 'export PATH=\"$HOME/.opencode/bin:$PATH\"' >> /home/node/.zshrc",
+        "install": "# Install OpenCode (as node user)\nRUN su - node -c 'curl -fsSL https://opencode.ai/install | bash' \\\n    && echo 'export PATH=\"$HOME/.opencode/bin:$PATH\"' >> /home/node/.zshrc",
         "note": "Check 'opencode --help' for available flags"
       },
-      "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GOOGLE_API_KEY"],
+      "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
       "credentialMount": null
     },
     "amp": {
@@ -70,8 +75,9 @@
       "command": "amp",
       "defaultArgs": [],
       "yoloArgs": ["--yolo"],
+      "promptArgs": [],
       "docker": {
-        "install": "# Install AMP CLI\nRUN curl -fsSL https://ampcode.com/install.sh | bash \\\n    && echo 'export PATH=\"$HOME/.amp/bin:$PATH\"' >> /home/node/.zshrc",
+        "install": "# Install AMP CLI (as node user)\nRUN su - node -c 'curl -fsSL https://ampcode.com/install.sh | bash' \\\n    && echo 'export PATH=\"$HOME/.amp/bin:$PATH\"' >> /home/node/.zshrc",
         "note": "Check 'amp --help' for available flags"
       },
       "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
@@ -83,6 +89,7 @@
       "command": "",
       "defaultArgs": [],
       "yoloArgs": [],
+      "promptArgs": [],
       "docker": {
         "install": "# Custom CLI - add your installation commands here"
       },

package/dist/templates/prompts.d.ts

@@ -33,6 +33,7 @@ export interface CliProviderConfig {
     command: string;
     defaultArgs: string[];
     yoloArgs: string[];
+    promptArgs: string[];
     docker: {
         install: string;
     };

package/dist/utils/config.d.ts

@@ -2,6 +2,7 @@ export interface CliConfig {
     command: string;
     args?: string[];
     yoloArgs?: string[];
+    promptArgs?: string[];
 }
 export interface RalphConfig {
     language: string;

package/dist/utils/config.js

@@ -3,9 +3,30 @@ import { join } from "path";
 export const DEFAULT_CLI_CONFIG = {
     command: "claude",
     args: ["--permission-mode", "acceptEdits"],
+    promptArgs: ["-p"],
 };
+// Lazy import to avoid circular dependency
+let _getCliProviders = null;
 export function getCliConfig(config) {
-    return config.cli ?? DEFAULT_CLI_CONFIG;
+    const cliConfig = config.cli ?? DEFAULT_CLI_CONFIG;
+    // If promptArgs is already set, use it
+    if (cliConfig.promptArgs !== undefined) {
+        return cliConfig;
+    }
+    // Look up promptArgs from cliProvider if available
+    if (config.cliProvider) {
+        if (!_getCliProviders) {
+            // Dynamic import to avoid circular dependency
+            _getCliProviders = require("../templates/prompts.js").getCliProviders;
+        }
+        const providers = _getCliProviders();
+        const provider = providers[config.cliProvider];
+        if (provider?.promptArgs !== undefined) {
+            return { ...cliConfig, promptArgs: provider.promptArgs };
+        }
+    }
+    // Default to -p for backwards compatibility
+    return { ...cliConfig, promptArgs: ["-p"] };
 }
 const RALPH_DIR = ".ralph";
 const CONFIG_FILE = "config.json";

package/dist/utils/prompt.js

@@ -68,6 +68,7 @@ export async function promptSelectWithArrows(message, options) {
             if (process.stdin.isTTY) {
                 process.stdin.setRawMode(false);
             }
+            process.stdin.pause();
             process.stdout.write("\x1B[?25h"); // Show cursor
         };
         process.stdin.on("data", onKeypress);
@@ -230,6 +231,7 @@ export async function promptMultiSelectWithArrows(message, options) {
             if (process.stdin.isTTY) {
                 process.stdin.setRawMode(false);
             }
+            process.stdin.pause();
             process.stdout.write("\x1B[?25h"); // Show cursor
         };
         process.stdin.on("data", onKeypress);

package/docs/run-state-machine.md

@@ -0,0 +1,68 @@
+# Run Command State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> ParseFlags : run(args)
+
+    ParseFlags --> DetermineMode
+
+    state DetermineMode {
+        [*] --> CheckLoopFlag
+        CheckLoopFlag --> LoopMode : --loop
+        CheckLoopFlag --> CheckIterationArg : no --loop
+        CheckIterationArg --> CountMode : number provided
+        CheckIterationArg --> AllMode : no number (default)
+    }
+
+    DetermineMode --> CheckItems
+
+    state "Check Items" as CheckItems {
+        [*] --> CreateFilteredPRD
+        CreateFilteredPRD --> HasIncomplete
+        HasIncomplete --> StartIteration : yes
+        HasIncomplete --> HandleComplete : no
+    }
+
+    state HandleComplete {
+        [*] --> CheckMode
+        CheckMode --> WaitForNewItems : LoopMode
+        CheckMode --> PrintComplete : AllMode/CountMode
+        WaitForNewItems --> PollLoop
+        PollLoop --> CheckNewItems : every 30s
+        CheckNewItems --> StartIteration : found
+        CheckNewItems --> PollLoop : not found
+        PrintComplete --> [*]
+    }
+
+    state "Start Iteration" as StartIteration
+
+    StartIteration --> RunCLI
+
+    state "Run CLI" as RunCLI {
+        [*] --> SpawnProcess
+        SpawnProcess --> WaitForExit
+        WaitForExit --> ProcessOutput
+    }
+
+    RunCLI --> CheckResult
+
+    state "Check Result" as CheckResult {
+        [*] --> CheckExitCode
+        CheckExitCode --> TrackFailure : non-zero
+        CheckExitCode --> ResetFailures : zero
+        TrackFailure --> CheckConsecutive
+        CheckConsecutive --> StopRun : >= 3 consecutive
+        CheckConsecutive --> CheckCompletionSignal : < 3
+        ResetFailures --> CheckCompletionSignal
+        CheckCompletionSignal --> HandleLoopComplete : COMPLETE signal
+        CheckCompletionSignal --> NextIteration : no signal
+        HandleLoopComplete --> WaitForNewItems : LoopMode
+        HandleLoopComplete --> PrintFinalStatus : AllMode/CountMode
+        StopRun --> [*]
+        PrintFinalStatus --> [*]
+    }
+
+    NextIteration --> CheckIterationLimit
+    CheckIterationLimit --> CheckItems : more iterations
+    CheckIterationLimit --> [*] : limit reached
+```

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "ralph-cli-sandboxed",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "AI-driven development automation CLI for Claude Code",
   "type": "module",
   "bin": {
-    "ralph": "./dist/index.js"
+    "ralph": "dist/index.js"
   },
   "main": "./dist/index.js",
   "files": [
@@ -17,7 +17,8 @@
     "copy-config": "mkdir -p dist/config && cp src/config/*.json dist/config/",
     "dev": "npx tsx src/index.ts",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "prepare": "npm run build"
   },
   "dependencies": {
     "readline": "^1.3.0"