ralph-codex 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -2,8 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.3] - 2026-01-22
+- Added comprehensive CLI test suite with vitest, harness, and fixtures.
+- Added GitHub Actions CI for Node 18/20/22.
+- Guarded run completion to require all tasks checked off.
+
+## [0.1.2] - 2026-01-22
+- Improved README with setup, defaults, Docker guidance, and troubleshooting.
+
 ## [0.1.1] - 2026-01-22
-- Added shell completion command with bash/zsh/fish support and dynamic suggestions.
+- Added shell completion command (bash/zsh/fish) with dynamic suggestions.
 
 ## [0.1.0] - 2026-01-21
 - Initial release.

package/README.md

@@ -1,5 +1,7 @@
 # ralph-codex
 
+![ralph-codex](docs/ralph-codex.jpg)
+
 Codex-first Ralph-style planning and run loops.
 
 ## What it does
@@ -9,7 +11,14 @@ Codex-first Ralph-style planning and run loops.
 - Optional Docker mode for reproducible runs.
 - Colorized Codex output in TTY for easier scanning (disable with `NO_COLOR=1`).
 
-![Ralph Codex normal workflow](docs/ralph-codex-workflow.png)
+## How it works
+
+- `plan` asks for success criteria, runs Codex, and writes `tasks.md`.
+- `run` executes tasks until `LOOP_COMPLETE`, updating `.ralph/` state and logs.
+- `revise` adds new tasks from feedback without touching existing items.
+- `view` and `reset` help you inspect and reset task status.
+
+![Ralph Codex workflow](docs/ralph-codex-workflow.png)
 
 ## Requirements
 
@@ -17,6 +26,19 @@ Codex-first Ralph-style planning and run loops.
 - Codex CLI installed and authenticated (`codex` available in PATH)
 - Docker (optional, only for Docker mode)
 
+## Codex CLI setup
+
+Install and verify:
+
+```bash
+npm install -g @openai/codex
+codex --help
+```
+
+Authenticate using the Codex CLI and/or create a profile in `~/.codex/config.toml`.
+Follow the auth guide at https://developers.openai.com/codex/auth.
+If you use profiles, pass `--profile` or set `codex.profile` in `ralph.config.yml`.
+
 ## Install
 
 ```bash
@@ -36,6 +58,45 @@ ralph-codex view
 ralph-codex reset
 ```
 
+## Demo (sample output)
+
+```text
+$ ralph-codex plan "Add screenshot flow"
+... (interactive prompts) ...
+tasks.md written
+$ ralph-codex run
+... (loop output) ...
+LOOP_COMPLETE
+```
+
+## Cookbook
+
+### Basic flow
+
+```bash
+ralph-codex init
+ralph-codex plan "Add screenshot flow for /demo" --output tasks.md
+ralph-codex run --max-iterations 10
+```
+
+### Docker flow
+
+```bash
+ralph-codex docker
+# Ensure docker.codex_install is set in ralph.config.yml
+ralph-codex plan "Add screenshot flow for /demo"
+ralph-codex run
+```
+
+### Low-touch automation (still interactive)
+
+Use a prefilled config and pass flags to minimize prompts. This CLI still expects a TTY.
+
+```bash
+ralph-codex plan "Add screenshot flow" --full-auto --reasoning low
+ralph-codex run --full-auto --reasoning low
+```
+
 ## Command reference
 
 Use `--help` with any command to see its available options.
@@ -174,6 +235,7 @@ run:
   max_iterations: 15
   max_iteration_seconds: null
   max_total_seconds: null
+  completion_promise: LOOP_COMPLETE
 ```
 
 Codex settings quick guide:
@@ -187,6 +249,20 @@ Enable `plan.auto_detect_success_criteria` to add detected checks based on repo
 
 CLI flags always override config values.
 
+## Defaults
+
+Defaults are from the template `ralph.config.yml`.
+
+| Setting | Default | Details |
+| --- | --- | --- |
+| `plan.tasks_path` | `tasks.md` | Output path for generated tasks. |
+| `plan.auto_detect_success_criteria` | `false` | Detect and suggest checks from the repo. |
+| `run.tasks_path` | `tasks.md` | Input path for tasks during runs. |
+| `run.max_iterations` | `15` | Max loop iterations before stopping. |
+| `run.completion_promise` | `LOOP_COMPLETE` | Completion token printed by the loop. |
+| `docker.enabled` | `false` | Enable Docker execution. |
+| `docker.use_for_plan` | `false` | Run planning inside Docker too. |
+
 ## Docker mode
 
 1. Run `ralph-codex docker` to pick a base image.
@@ -194,6 +270,20 @@ CLI flags always override config values.
 3. Run `ralph-codex plan` and `ralph-codex run` as usual. Enable `docker.use_for_plan`
    if you want planning to happen inside Docker as well.
 
+Why Docker (especially with `danger-full-access`):
+- Isolation: lets you grant broad permissions inside the container without exposing your host.
+- Reproducibility: consistent OS/package stack across runs and teammates.
+- Safer cleanup: delete the container/image to reset state.
+
+Why `danger-full-access`:
+- Fewer approval prompts for tooling that needs broad filesystem or network access.
+- Works better for complex build/test flows that span many paths.
+- Faster iterations when you trust the environment (best paired with Docker).
+
+> **Warning**: Avoid `danger-full-access` on your host unless you fully trust the prompts,
+> scripts, and dependencies. It grants broad access to your machine and can write
+> outside the repo. Prefer Docker when you need this mode.
+
 `Dockerfile.ralph` is generated automatically when Docker is enabled.
 
 ## Files created
@@ -207,12 +297,24 @@ CLI flags always override config values.
 Codex output is colorized when stdout is a TTY. Plan uses spinners and run shows a task
 progress bar when interactive. Set `NO_COLOR=1` to disable color styling.
 
+## Exit codes
+
+- `0` success.
+- `1` invalid usage or runtime error.
+
 ## Troubleshooting
 
 - `codex: command not found` -> install Codex CLI and ensure it is in PATH.
+- Auth errors (401/403) -> authenticate Codex CLI or select a valid profile.
+- `Missing tasks.md` -> run `ralph-codex plan` first or pass `--tasks`.
 - Docker errors -> start Docker Desktop/Colima and retry.
-- Plan/run fail to read config -> verify `ralph.config.yml` path or pass `--config`.
+- Config read errors -> verify `ralph.config.yml` path or pass `--config`.
+
+## Changelog and license
+
+- Changelog: `CHANGELOG.md`
+- License: `LICENSE` (MIT)
 
-## License
+## Privacy
 
-MIT
+ralph-codex does not add its own telemetry. It sends prompts and context to the Codex CLI you configure; follow your Codex policies and settings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-codex",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Codex-first Ralph-style planning and run loops",
   "repository": {
     "type": "git",
@@ -25,6 +25,10 @@
     "node": ">=18"
   },
   "packageManager": "npm@10.8.2",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "dependencies": {
     "cli-progress": "^3.12.0",
     "enquirer": "^2.4.1",
@@ -32,6 +36,9 @@
     "ora": "^5.4.1",
     "picocolors": "^1.0.0"
   },
+  "devDependencies": {
+    "vitest": "^1.6.0"
+  },
   "files": [
     "bin",
     "src",

package/src/commands/completion.js

@@ -130,9 +130,9 @@ _ralph_codex_completion_promise_list() {
 
 _ralph_codex() {
   local cur prev cmd
-  cur="\\${COMP_WORDS[COMP_CWORD]}"
-  prev="\\${COMP_WORDS[COMP_CWORD-1]}"
-  cmd="\\${COMP_WORDS[1]}"
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  cmd="\${COMP_WORDS[1]}"
 
   local commands="init plan run revise refine view reset docker completion help"
   local root_opts="--help -h --version -v"
@@ -174,6 +174,10 @@ _ralph_codex() {
           COMPREPLY=( $(compgen -W "$tasks" -- "$cur") $(compgen -f -- "$cur") )
           return 0
           ;;
+        --idea-file)
+          COMPREPLY=( $(compgen -f -- "$cur") )
+          return 0
+          ;;
         --sandbox)
           COMPREPLY=( $(compgen -W "read-only workspace-write danger-full-access" -- "$cur") )
           return 0
@@ -199,7 +203,7 @@ _ralph_codex() {
           return 0
           ;;
       esac
-      local opts="--output --tasks --max-iterations --config --model -m --profile -p --sandbox --no-sandbox --ask-for-approval --full-auto --reasoning --detect-success-criteria --no-detect-success-criteria --help -h"
+      local opts="--output --tasks --idea-file --stdin --max-iterations --config --model -m --profile -p --sandbox --no-sandbox --ask-for-approval --full-auto --reasoning --detect-success-criteria --no-detect-success-criteria --help -h"
       COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
       return 0
       ;;
@@ -525,6 +529,8 @@ _ralph_codex() {
           _arguments \\
             '--output[Write tasks to a custom file]:path:_ralph_codex_tasks' \\
             '--tasks[Write tasks to a custom file]:path:_ralph_codex_tasks' \\
+            '--idea-file[Read idea from a markdown file]:file:_files' \\
+            '--stdin[Read idea from stdin]' \\
             '--max-iterations[Max planning iterations]:number:' \\
             '--config[Path to ralph.config.yml]:file:_ralph_codex_configs' \\
             '(-m --model)'{-m,--model}'[Codex model]:model:_ralph_codex_models' \\
@@ -745,6 +751,8 @@ complete -c ralph-codex -n '__fish_seen_subcommand_from init' -l no-gitignore -d
 
 complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l output -r -a '(__ralph_codex_tasks)' -d 'Write tasks to a custom file'
 complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l tasks -r -a '(__ralph_codex_tasks)' -d 'Write tasks to a custom file'
+complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l idea-file -r -a '(__fish_complete_path)' -d 'Read idea from a markdown file'
+complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l stdin -d 'Read idea from stdin'
 complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l max-iterations -r -d 'Max planning iterations'
 complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l config -r -a '(__ralph_codex_configs)' -d 'Path to ralph.config.yml'
 complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -s m -l model -r -a '(__ralph_codex_models)' -d 'Codex model'

package/src/commands/docker.js

@@ -8,6 +8,7 @@ const { Confirm } = enquirer;
 
 const root = process.cwd();
 const defaultConfigPath = path.join(root, "ralph.config.yml");
+const isTestMode = process.env.RALPH_TEST_MODE === "1";
 
 const argv = process.argv.slice(2);
 let configPath = null;
@@ -122,12 +123,12 @@ function runCodex(prompt, codexConfig) {
 
 function buildPrompt(nodeVersion) {
   const nodeLine = nodeVersion ? `Node version: ${nodeVersion}` : "Node 20+";
-  return `Encuentra la mejor imagen base de Docker para este proyecto.
-Considera que necesita ejecutar npm scripts, módulos nativos y evitar Alpine.
+  return `Find the best Docker base image for this project.
+Consider that it needs to run npm scripts, native modules, and should avoid Alpine.
 ${nodeLine}
 
-Responde SOLO con una línea en este formato:
-BASE_IMAGE: <imagen>`;
+Respond with a single line in this format:
+BASE_IMAGE: <image>`;
 }
 
 async function main() {
@@ -148,13 +149,13 @@ async function main() {
     process.exit(1);
   }
 
-  const confirm = new Confirm({
-    name: "confirm",
-    message: `Set docker.enabled=true and base_image=${baseImage}?`,
-    initial: true,
-  });
-
-  const approved = await confirm.run();
+  const approved = isTestMode
+    ? true
+    : await new Confirm({
+        name: "confirm",
+        message: `Set docker.enabled=true and base_image=${baseImage}?`,
+        initial: true,
+      }).run();
   if (!approved) {
     process.stdout.write("Aborted by user.\n");
     process.exit(1);

package/src/commands/init.js

@@ -7,6 +7,7 @@ const { AutoComplete, Confirm, Input, Toggle } = enquirer;
 
 const root = process.cwd();
 const argv = process.argv.slice(2);
+const isTestMode = process.env.RALPH_TEST_MODE === "1";
 
 let force = false;
 let configPath = null;
@@ -42,6 +43,7 @@ const targetPath = configPath
   : path.join(root, "ralph.config.yml");
 
 async function confirmOverwrite() {
+  if (isTestMode) return true;
   const confirm = new Confirm({
     name: "overwrite",
     message: `Overwrite existing ${path.relative(root, targetPath)}?`,
@@ -224,6 +226,16 @@ async function promptModelChoice() {
 }
 
 async function collectCodexConfig() {
+  if (isTestMode) {
+    return {
+      model: null,
+      profile: null,
+      sandbox: null,
+      ask_for_approval: null,
+      full_auto: false,
+      model_reasoning_effort: null,
+    };
+  }
   const model = await promptModelChoice();
   const profile = await promptOptionalInput(
     "Codex CLI profile (optional; leave blank to use Codex default)",
@@ -359,13 +371,15 @@ async function main() {
 
   const content = fs.readFileSync(templatePath, "utf8");
   const codexConfig = await collectCodexConfig();
-  const useDocker = await new Toggle({
-    name: "use_docker",
-    message: "Use Docker for the loop? (adds a docker section)",
-    enabled: "Yes",
-    disabled: "No",
-    initial: false,
-  }).run();
+  const useDocker = isTestMode
+    ? process.env.RALPH_TEST_USE_DOCKER === "1"
+    : await new Toggle({
+        name: "use_docker",
+        message: "Use Docker for the loop? (adds a docker section)",
+        enabled: "Yes",
+        disabled: "No",
+        initial: false,
+      }).run();
 
   let updated = content;
   updated = setYamlValue(updated, "model", codexConfig.model);

package/src/commands/plan.js

@@ -10,10 +10,13 @@ const { AutoComplete, Confirm, Editor, Input, MultiSelect } = enquirer;
 
 const root = process.cwd();
 const agentDir = path.join(root, ".ralph");
+const isTestMode = process.env.RALPH_TEST_MODE === "1";
 
 const argv = process.argv.slice(2);
 let maxIterations = "1";
 let tasksPath = "tasks.md";
+let ideaFile = null;
+let readStdin = false;
 let noSandbox = false;
 let sandbox = null;
 let fullAuto = false;
@@ -27,6 +30,7 @@ let autoDetectSuccessCriteria = null;
 let reasoningChoice;
 let showHelp = false;
 const ideaParts = [];
+let idea = "";
 
 for (let i = 0; i < argv.length; i += 1) {
   const arg = argv[i];
@@ -49,6 +53,20 @@ for (let i = 0; i < argv.length; i += 1) {
     i += 1;
     continue;
   }
+  if (arg === "--idea-file") {
+    const value = argv[i + 1];
+    if (!value || (value.startsWith("-") && value !== "-")) {
+      console.error("Missing --idea-file <path>.");
+      process.exit(1);
+    }
+    ideaFile = value;
+    i += 1;
+    continue;
+  }
+  if (arg === "--stdin") {
+    readStdin = true;
+    continue;
+  }
   if (arg === "--no-sandbox") {
     noSandbox = true;
     continue;
@@ -109,6 +127,8 @@ function printHelp() {
       `${colors.yellow("Options:")}\n` +
       `  ${colors.green("--output <path>")}                 Write tasks to a custom file (alias of --tasks)\n` +
       `  ${colors.green("--tasks <path>")}                  Write tasks to a custom file (default: tasks.md)\n` +
+      `  ${colors.green("--idea-file <path>")}              Read idea from a markdown file ('-' for stdin)\n` +
+      `  ${colors.green("--stdin")}                         Read idea from stdin (paste then Ctrl-D)\n` +
       `  ${colors.green("--max-iterations <n>")}            Max planning iterations (default: 1)\n` +
       `  ${colors.green("--config <path>")}                 Path to ralph.config.yml\n` +
       `  ${colors.green("--model <name>, -m")}              Codex model\n` +
@@ -129,16 +149,24 @@ if (showHelp) {
   process.exit(0);
 }
 
-const idea = ideaParts.join(" ").trim();
+const promptPath = path.join(agentDir, "ralph-plan-prompt.md");
 
-if (!idea) {
-  console.error(
-    'Usage: ralph-codex plan "<idea>" [--output <path>] [--tasks <path>] [--max-iterations <n>]',
-  );
-  process.exit(1);
+function readIdeaFromStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (_) {
+    return "";
+  }
 }
 
-const promptPath = path.join(agentDir, "ralph-plan-prompt.md");
+function readIdeaFromFile(filePath) {
+  const resolved = path.resolve(root, filePath);
+  if (!fs.existsSync(resolved)) {
+    console.error(`Missing idea file: ${filePath}`);
+    process.exit(1);
+  }
+  return fs.readFileSync(resolved, "utf8");
+}
 function loadConfig(configFilePath) {
   if (!configFilePath) return {};
   if (!fs.existsSync(configFilePath)) return {};
@@ -175,7 +203,7 @@ function resolveDockerConfig(config) {
       ? dockerConfig.pip_packages
       : [],
     useForPlan: Boolean(dockerConfig.use_for_plan),
-    tty: dockerConfig.tty ?? "auto",
+    tty: dockerConfig.tty ?? false,
   };
 }
 
@@ -675,6 +703,7 @@ Context scan (read-only):
   pyproject.toml, requirements.txt, go.mod, Cargo.toml, pom.xml, build.gradle, Makefile,
   .nvmrc, Dockerfile, etc. Only inspect files that exist.
 - Use this context to infer file locations, tooling, and sensible commands.
+ - You may use read-only commands like ls, rg, and cat to inspect files.
 
 Requirements:
 - If there are open questions, ask them first and do not write ${tasksPath}.
@@ -693,13 +722,18 @@ Requirements:
 - Tasks must be atomic, ordered, and verifiable. Include exact file paths,
   commands to run (if any), and expected outcomes. Avoid vague verbs like "handle" or "improve".
 - Keep scope minimal: avoid refactors unless required by the idea or to unblock tasks.
+- Use this exact section order and headings in ${tasksPath}:
+  1) # Tasks
+  2) ## Assumptions (only if needed)
+  3) ## Success criteria
+  4) ## Required tools
 ${successCriteriaBlock}
 - Include a "Required tools" section using this exact format:
   - \`- apt: <comma-separated packages or none>\`
   - \`- npm: <comma-separated packages or none>\`
   - \`- pip: <comma-separated packages or none>\`
 - Do not edit any files other than ${tasksPath}.
-- Do not run commands, tests, or start dev servers during planning.
+- Do not run write commands, tests, installs, or start dev servers during planning.
 
 When done, output exactly: LOOP_COMPLETE
 `;
@@ -856,6 +890,13 @@ async function selectSuccessCriteria(
   standardChoices,
   detectedChoices = []
 ) {
+  if (isTestMode) {
+    const safeDefaults =
+      defaultCriteria && defaultCriteria.length > 0
+        ? defaultCriteria
+        : standardChoices;
+    return { mode: "manual", criteria: safeDefaults || [] };
+  }
   const autoChoiceValue = "__auto__";
   const customChoiceValue = "__custom__";
   const defaults =
@@ -949,6 +990,7 @@ async function selectSuccessCriteria(
 }
 
 async function confirmPlan(tasksFile) {
+  if (isTestMode) return true;
   const content = fs.readFileSync(tasksFile, "utf8");
   process.stdout.write(`\n${colors.cyan("--- Proposed tasks.md ---")}\n\n`);
   process.stdout.write(content);
@@ -972,6 +1014,7 @@ async function readRevisionFeedback() {
 }
 
 async function confirmResetState(tasksFilePath, agentPath) {
+  if (isTestMode) return false;
   const hasTasks = fs.existsSync(tasksFilePath);
   const hasAgent = fs.existsSync(agentPath);
   if (!hasTasks && !hasAgent) return false;
@@ -994,6 +1037,23 @@ function resetState(tasksFilePath, agentPath) {
 }
 
 async function main() {
+  const ideaFromArgs = ideaParts.join(" ").trim();
+  if (ideaFile) {
+    idea = ideaFile === "-" ? readIdeaFromStdin() : readIdeaFromFile(ideaFile);
+  } else if (readStdin || (!ideaFromArgs && !process.stdin.isTTY)) {
+    idea = readIdeaFromStdin();
+  } else {
+    idea = ideaFromArgs;
+  }
+
+  idea = String(idea || "").trim();
+  if (!idea) {
+    console.error(
+      'Usage: ralph-codex plan "<idea>" [--idea-file <path>] [--stdin] [--output <path>] [--tasks <path>] [--max-iterations <n>]',
+    );
+    process.exit(1);
+  }
+
   const resolvedConfigPath = configPath || path.join(root, "ralph.config.yml");
   const config = loadConfig(resolvedConfigPath);
   const codexConfig = config?.codex || {};

package/src/commands/revise.js

@@ -4,6 +4,12 @@ import path from "path";
 import enquirer from "enquirer";
 import yaml from "js-yaml";
 import { colors, createLogStyler, createSpinner } from "../ui/terminal.js";
+import {
+  diffCriteria,
+  diffTasks,
+  parseSuccessCriteria,
+  parseTasks,
+} from "../lib/tasks.js";
 
 const { AutoComplete, Confirm, Editor, Input } = enquirer;
 
@@ -223,91 +229,6 @@ async function readFeedback(promptMessage) {
   return input.run();
 }
 
-function parseTasks(content) {
-  const tasks = [];
-  const lines = content.split(/\r?\n/);
-  for (const line of lines) {
-    const match = line.match(/^\s*[-*]\s+\[([ x~])\]\s+(.*)$/);
-    if (!match) continue;
-    const statusToken = match[1].toLowerCase();
-    const status =
-      statusToken === "x" ? "done" : statusToken === "~" ? "blocked" : "pending";
-    tasks.push({
-      status,
-      text: match[2].trim(),
-      raw: line.trim(),
-    });
-  }
-  return tasks;
-}
-
-function normalizeTaskText(text) {
-  return String(text || "")
-    .toLowerCase()
-    .replace(/\s+/g, " ")
-    .trim();
-}
-
-function parseSuccessCriteria(content) {
-  const lines = content.split(/\r?\n/);
-  let start = -1;
-  for (let i = 0; i < lines.length; i += 1) {
-    if (/^(#+\s*)?success criteria\b/i.test(lines[i].trim())) {
-      start = i;
-      break;
-    }
-  }
-  if (start === -1) return [];
-  const items = [];
-  for (let i = start + 1; i < lines.length; i += 1) {
-    const line = lines[i].trim();
-    if (!line) continue;
-    if (/^#+\s+/.test(line)) break;
-    if (line.startsWith("- ")) items.push(line.slice(2).trim());
-    if (line.startsWith("* ")) items.push(line.slice(2).trim());
-  }
-  return items;
-}
-
-function diffTasks(oldTasks, newTasks) {
-  const oldSet = new Set(oldTasks.map((task) => normalizeTaskText(task.text)));
-  const newSet = new Set(newTasks.map((task) => normalizeTaskText(task.text)));
-
-  const additions = newTasks.filter(
-    (task) => !oldSet.has(normalizeTaskText(task.text))
-  );
-  const removals = oldTasks.filter(
-    (task) => !newSet.has(normalizeTaskText(task.text))
-  );
-
-  const modified = [];
-  const compareCount = Math.min(oldTasks.length, newTasks.length);
-  for (let i = 0; i < compareCount; i += 1) {
-    const before = oldTasks[i];
-    const after = newTasks[i];
-    if (
-      before.status !== after.status ||
-      normalizeTaskText(before.text) !== normalizeTaskText(after.text)
-    ) {
-      modified.push({
-        index: i + 1,
-        before,
-        after,
-      });
-    }
-  }
-
-  return { additions, removals, modified };
-}
-
-function diffCriteria(oldCriteria, newCriteria) {
-  const oldSet = new Set(oldCriteria);
-  const newSet = new Set(newCriteria);
-  const added = newCriteria.filter((item) => !oldSet.has(item));
-  const removed = oldCriteria.filter((item) => !newSet.has(item));
-  return { added, removed };
-}
-
 function renderChanges(changes) {
   if (changes.additions.length > 0) {
     process.stdout.write(`${colors.cyan("Proposed new tasks:")}\n`);

package/src/commands/run.js

@@ -278,7 +278,7 @@ function resolveDockerConfig(config) {
     fixAttempts: Number(dockerConfig.fix_attempts || 2),
     fixUseHost: dockerConfig.fix_use_host !== false,
     fixLog: dockerConfig.fix_log || ".ralph/docker-build.log",
-    tty: dockerConfig.tty ?? "auto",
+    tty: dockerConfig.tty ?? false,
     cleanup: dockerConfig.cleanup || "none",
   };
 }
@@ -356,6 +356,8 @@ ${result.output}
 Constraints:
 - Only edit ${dockerConfig.dockerfile}
 - Do not change other files
+- Keep the existing base image unless the error requires changing it
+- Do not add new dependencies unless required by the error
 - Do not ask questions
 - Output exactly: LOOP_COMPLETE
 `;
@@ -1142,8 +1144,33 @@ async function main() {
     }
 
     if (hasCompletion(result.output)) {
-      completed = true;
-      break;
+      const completionProgress = getTaskProgress(tasksFile);
+      if (
+        completionProgress.total > 0 &&
+        completionProgress.completed === completionProgress.total
+      ) {
+        completed = true;
+        break;
+      }
+
+      const pendingCount = Math.max(
+        0,
+        completionProgress.total -
+          completionProgress.completed -
+          completionProgress.blocked,
+      );
+      const reason =
+        completionProgress.total === 0
+          ? "no tasks detected"
+          : `${pendingCount} pending, ${completionProgress.blocked} blocked`;
+      notes.push(
+        `Completion token received but tasks remain incomplete (${reason}).`,
+      );
+      process.stdout.write(
+        `${colors.yellow(
+          "Completion token received but tasks remain incomplete; continuing.",
+        )}\n`,
+      );
     }
 
     if (iterationTimedOut) {

package/src/commands/view.js

@@ -2,6 +2,7 @@ import fs from "fs";
 import path from "path";
 import yaml from "js-yaml";
 import { colors } from "../ui/terminal.js";
+import { parseSuccessCriteria, parseTasks } from "../lib/tasks.js";
 
 const root = process.cwd();
 const argv = process.argv.slice(2);
@@ -156,21 +157,6 @@ function formatStatus(status) {
   return { raw, display: colors.gray(raw) };
 }
 
-function parseTasks(content) {
-  const tasks = [];
-  const lines = content.split(/\r?\n/);
-  let index = 0;
-  for (const line of lines) {
-    const match = line.match(/^\s*[-*]\s+\[([ x~])\]\s+(.*)$/);
-    if (!match) continue;
-    index += 1;
-    const statusToken = match[1].toLowerCase();
-    const status =
-      statusToken === "x" ? "done" : statusToken === "~" ? "blocked" : "pending";
-    tasks.push({ index, status, text: match[2].trim() });
-  }
-  return tasks;
-}
 
 function summarizeTasks(tasks) {
   const total = tasks.length;
@@ -186,26 +172,6 @@ function filterTasks(tasks, filter) {
   return tasks.filter((task) => task.status === filter);
 }
 
-function extractSuccessCriteria(content) {
-  const lines = content.split(/\r?\n/);
-  let start = -1;
-  for (let i = 0; i < lines.length; i += 1) {
-    if (/^(#+\s*)?success criteria\b/i.test(lines[i].trim())) {
-      start = i;
-      break;
-    }
-  }
-  if (start === -1) return [];
-  const items = [];
-  for (let i = start + 1; i < lines.length; i += 1) {
-    const line = lines[i].trim();
-    if (!line) continue;
-    if (/^#+\s+/.test(line)) break;
-    if (line.startsWith("- ")) items.push(line.slice(2).trim());
-    if (line.startsWith("* ")) items.push(line.slice(2).trim());
-  }
-  return items;
-}
 
 function getLastBlocker(logPath) {
   if (!fs.existsSync(logPath)) return "";
@@ -339,6 +305,7 @@ function getConfigRows(config) {
       use_for_plan: false,
       base_image: "node:20-bullseye",
       codex_install: "",
+      tty: false,
     },
     plan: {
       tasks_path: "tasks.md",
@@ -468,7 +435,7 @@ function renderOnce({ allowMissingTasks }) {
     const summary = summarizeTasks(allTasks);
     const filtered = filterTasks(allTasks, only);
     const sliced = limit > 0 ? filtered.slice(0, limit) : filtered;
-    const criteria = extractSuccessCriteria(tasksContent);
+    const criteria = parseSuccessCriteria(tasksContent);
 
     tasksData = {
       path: resolvedTasksPath,

package/src/lib/tasks.js

@@ -0,0 +1,97 @@
+function parseTasks(content) {
+  const tasks = [];
+  const lines = String(content || "").split(/\r?\n/);
+  let index = 0;
+
+  for (const line of lines) {
+    const match = line.match(/^\s*[-*]\s+\[([ x~])\]\s+(.*)$/);
+    if (!match) continue;
+    index += 1;
+    const statusToken = match[1].toLowerCase();
+    const status =
+      statusToken === "x" ? "done" : statusToken === "~" ? "blocked" : "pending";
+    tasks.push({
+      index,
+      status,
+      text: match[2].trim(),
+      raw: line.trim(),
+    });
+  }
+
+  return tasks;
+}
+
+function parseSuccessCriteria(content) {
+  const lines = String(content || "").split(/\r?\n/);
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (/^(#+\s*)?success criteria\b/i.test(lines[i].trim())) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return [];
+  const items = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    if (/^#+\s+/.test(line)) break;
+    if (line.startsWith("- ")) items.push(line.slice(2).trim());
+    if (line.startsWith("* ")) items.push(line.slice(2).trim());
+  }
+  return items;
+}
+
+function normalizeTaskText(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function diffTasks(oldTasks, newTasks) {
+  const oldSet = new Set(oldTasks.map((task) => normalizeTaskText(task.text)));
+  const newSet = new Set(newTasks.map((task) => normalizeTaskText(task.text)));
+
+  const additions = newTasks.filter(
+    (task) => !oldSet.has(normalizeTaskText(task.text))
+  );
+  const removals = oldTasks.filter(
+    (task) => !newSet.has(normalizeTaskText(task.text))
+  );
+
+  const modified = [];
+  const compareCount = Math.min(oldTasks.length, newTasks.length);
+  for (let i = 0; i < compareCount; i += 1) {
+    const before = oldTasks[i];
+    const after = newTasks[i];
+    if (
+      before.status !== after.status ||
+      normalizeTaskText(before.text) !== normalizeTaskText(after.text)
+    ) {
+      modified.push({
+        index: i + 1,
+        before,
+        after,
+      });
+    }
+  }
+
+  return { additions, removals, modified };
+}
+
+function diffCriteria(oldCriteria, newCriteria) {
+  const oldSet = new Set(oldCriteria);
+  const newSet = new Set(newCriteria);
+  const added = newCriteria.filter((item) => !oldSet.has(item));
+  const removed = oldCriteria.filter((item) => !newSet.has(item));
+  return { added, removed };
+}
+
+export {
+  diffCriteria,
+  diffTasks,
+  normalizeTaskText,
+  parseSuccessCriteria,
+  parseTasks,
+};

package/templates/ralph.config.yml

@@ -18,7 +18,7 @@ docker:
   codex_install: npm install -g @openai/codex
   codex_home: .ralph/codex # Writable codex home inside the repo
   mount_codex_config: true # Seed codex_home from host ~/.codex if empty
-  tty: auto # auto | true | false
+  tty: false # auto | true | false
   pass_env:
     - OPENAI_API_KEY
   apt_packages: