Fix Stuck AI Planner and Enable Live Output

>git push -u fork fix/discord-infinite-loop-and-streaming

Exit code 128
fatal: 'fork' does not appear to be a git repository
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

>git remote -v

origin	git@github.com:aaron777collins/portableralph.git (fetch)
origin	git@github.com:aaron777collins/portableralph.git (push)

>git remote add fork git@github.com:thebigjc/portableralph.git && git push -u fork fix/discord-infinite-loop-and-streaming

branch 'fix/discord-infinite-loop-and-streaming' set up to track 'fork/fix/discord-infinite-loop-and-streaming'.
remote: 
remote: Create a pull request for 'fix/discord-infinite-loop-and-streaming' on GitHub by visiting:        
remote:      https://github.com/thebigjc/portableralph/pull/new/fix/discord-infinite-loop-and-streaming        
remote: 
To github.com:thebigjc/portableralph.git
 * [new branch]      fix/discord-infinite-loop-and-streaming -> fix/discord-infinite-loop-and-streaming

>git add README.md && git commit -m "$(cat <<'EOF'
doc: Add Configuration section with RALPH_MODEL to README

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

[fix/discord-infinite-loop-and-streaming bd9afbb] doc: Add Configuration section with RALPH_MODEL to README
 1 file changed, 26 insertions(+)

>git push fork fix/discord-infinite-loop-and-streaming

To github.com:thebigjc/portableralph.git
   6a520a1..bd9afbb  fix/discord-infinite-loop-and-streaming -> fix/discord-infinite-loop-and-streaming

>ps aux | grep -E 'ralph|claude' | grep -v grep | grep -v 'resume'

jc        942971  0.0  0.0   8016  4096 pts/0    S+   11:35   0:00 /bin/bash /mnt/dest-btrfs/home/jc/ralph/ralph.sh plan.md plan
jc        943048  3.6  0.7 32937848 257292 pts/0 Sl+  11:35   0:25 claude

>ps aux | grep -E 'ralph|claude' | grep -v grep | grep -v 'resume'

jc        966865  0.0  0.0   8016  4096 pts/0    S+   11:47   0:00 /bin/bash /mnt/dest-btrfs/home/jc/ralph/ralph.sh plan.md plan
jc        966935  8.2  0.7 32923896 245028 pts/0 Sl+  11:47   0:05 claude

>claude -p --help 2>&1 | head -30

Error: Claude Code cannot be launched inside another Claude Code session.
Nested sessions share runtime resources and will crash all active sessions.
To bypass this check, unset the CLAUDECODE environment variable.

>CLAUDECODE= claude --help 2>&1 | grep -A3 '\-p\b\|--print\|output-format\|--verbose'

Claude Code - starts an interactive session by default, use -p/--print for
non-interactive output

Arguments:
--
  --fallback-model <model>                          Enable automatic fallback to specified model when default model is overloaded (only works with --print)
  --file <specs...>                                 File resources to download at startup. Format: file_id:relative_path (e.g., --file file_abc:doc.txt file_def:img.png)
  --fork-session                                    When resuming, create a new session ID instead of reusing the original (use with --resume or --continue)
  --from-pr [value]                                 Resume a session linked to a PR by PR number/URL, or open interactive picker with optional search term
--
  --include-partial-messages                        Include partial message chunks as they arrive (only works with --print and --output-format=stream-json)
  --input-format <format>                           Input format (only works with --print): "text" (default), or "stream-json" (realtime streaming input) (choices: "text", "stream-json")
  --json-schema <schema>                            JSON Schema for structured output validation. Example: {"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}
  --max-budget-usd <amount>                         Maximum dollar amount to spend on API calls (only works with --print)
  --mcp-config <configs...>                         Load MCP servers from JSON files or strings (space-separated)
  --mcp-debug                                       [DEPRECATED. Use --debug instead] Enable MCP debug mode (shows MCP server errors)
  --model <model>                                   Model for the current session. Provide an alias for the latest model (e.g. 'sonnet' or 'opus') or a model's full name (e.g. 'claude-sonnet-4-5-20250929').
--
  --no-session-persistence                          Disable session persistence - sessions will not be saved to disk and cannot be resumed (only works with --print)
  --output-format <format>                          Output format (only works with --print): "text" (default), "json" (single result), or "stream-json" (realtime streaming) (choices: "text", "json", "stream-json")
  --permission-mode <mode>                          Permission mode to use for the session (choices: "acceptEdits", "bypassPermissions", "default", "delegate", "dontAsk", "plan")
  --plugin-dir <paths...>                           Load plugins from directories for this session only (repeatable)
  -p, --print                                       Print response and exit (useful for pipes). Note: The workspace trust dialog is skipped when Claude is run with the -p mode. Only use this flag in directories you trust.
  --replay-user-messages                            Re-emit user messages from stdin back on stdout for acknowledgment (only works with --input-format=stream-json and --output-format=stream-json)
  -r, --resume [value]                              Resume a conversation by session ID, or open interactive picker with optional search term
  --session-id <uuid>                               Use a specific session ID for the conversation (must be a valid UUID)
  --setting-sources <sources>                       Comma-separated list of setting sources to load (user, project, local).
--
  --verbose                                         Override verbose mode setting from config
  -v, --version                                     Output the version number

Commands:

>ls /tmp/ralph_*.lock 2>/dev/null; echo "---"; ls /mnt/dest-btrfs/home/jc/ralph/*PROGRESS* 2>/dev/null; echo "---"; ls /mnt/dest-btrfs/home/jc/*PROGRESS* 2>/dev/null

The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.

>CLAUDECODE="" bash -c 'echo "Say hello in one word" | claude -p --output-format stream-json 2>/dev/null | head -20'

(empty result)

>CLAUDECODE="" bash -c 'echo "Say hello in one word" | claude -p --output-format stream-json 2>/tmp/claude_stderr.txt | cat > /tmp/claude_stream_test.txt; echo "exit: $?"'

exit: 0

>cat /tmp/claude_stream_test.txt; echo "---"; cat /tmp/claude_stderr.txt

---
Error: When using --print, --output-format=stream-json requires --verbose

>CLAUDECODE="" bash -c 'echo "Say hello in one word" | claude -p --output-format stream-json --verbose 2>/dev/null > /tmp/claude_stream_test.txt; echo "exit: $?"'

exit: 0

>git push fork fix/discord-infinite-loop-and-streaming

To github.com:thebigjc/portableralph.git
   bd9afbb..c953b6b  fix/discord-infinite-loop-and-streaming -> fix/discord-infinite-loop-and-streaming

>ls ~/src/mage/*PROGRESS* 2>/dev/null

/mnt/dest-btrfs/home/jc/src/mage/plan_PROGRESS.md

>git add ralph.sh && git commit -m "$(cat <<'EOF'
feat: Show tool activity in streaming output

Display tool use events (Read, Grep, Bash, etc.) in blue between
text output so users can see what Claude is doing while it works,
not just sporadic text between long silences.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

[fix/discord-infinite-loop-and-streaming 41ccdb7] feat: Show tool activity in streaming output
 1 file changed, 9 insertions(+), 2 deletions(-)

>git push fork fix/discord-infinite-loop-and-streaming

To github.com:thebigjc/portableralph.git
   c953b6b..41ccdb7  fix/discord-infinite-loop-and-streaming -> fix/discord-infinite-loop-and-streaming

>gh pr edit 4 --repo aaron777collins/portableralph --body "$(cat <<'EOF'
## Summary
- **Fix infinite loop in `notify.sh`**: The Discord bold formatting conversion (`*text*` → `**text**`) used a `while` loop where the output still matched the input regex, causing 100% CPU spin forever. Replaced with single-pass left-to-right string processing.
- **Stream Claude output in real-time**: Changed `ralph.sh` to use `--output-format stream-json` and pipe through `jq` to display text and tool activity as Claude works, instead of buffering all output until completion.
- **Make model configurable**: Use `$RALPH_MODEL` env var instead of hardcoded `sonnet`. Document in README.
- **Fix decrypt ordering**: Move `decrypt-env` before config validation so decrypted values are validated.
- **Fix `local` outside functions**: Remove invalid `local` keywords in `setup-notifications.sh`.

### Streaming output example

```
══════════════════ ITERATION 1 ══════════════════

I'll start by reading the plan and progress files, then explore the codebase.
  → Read: /home/user/project/plan.md
  → Read: /home/user/project/plan_PROGRESS.md
Now let me explore the codebase structure to understand what's needed.
  → Task: Explore the project structure and dependencies
  → Read: /home/user/project/src/lib.rs
  → Grep /register_cards/
  → Bash: cargo check -p my-crate 2>&1 | tail -20
Based on my analysis, here are the implementation tasks...
  → Edit: /home/user/project/plan_PROGRESS.md
```

## Test plan
- [ ] Run `ralph notify test` with Discord configured — verify notification sends without hanging
- [ ] Run `ralph plan.md plan` — verify streaming output shows text and tool activity in real-time
- [ ] Run with `RALPH_MODEL=claude-opus-4-6 ralph plan.md plan` — verify model override works
- [ ] Run `ralph notify setup` — verify setup completes without bash errors
- [ ] Run without `jq` installed — verify graceful fallback to buffered output

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

https://github.com/aaron777collins/portableralph/pull/4

I now have a comprehensive understanding of the entire iannuttall/ralph codebase. Here is the full feature inventory.

---

# Comprehensive Feature Inventory: iannuttall/ralph

**Repository:** https://github.com/iannuttall/ralph
**Description:** A minimal, file-based agent loop for autonomous coding.
**Version:** 0.1.3 (npm package: `@iannuttall/ralph`)
**License:** MIT

---

## 1. CORE ARCHITECTURE

### 1.1 File-Based Agent Loop
- **What it does:** Treats files and git as memory rather than model context. Each iteration starts fresh, reads on-disk state, and commits work for one story at a time.
- **How:** The main loop (`loop.sh`) is a bash script that iterates up to `MAX_ITERATIONS` (default 25), selecting one story per iteration, rendering a prompt, invoking an agent CLI, and processing the result. The `while`/`for` loop with `sleep 2` between iterations drives the cycle.

### 1.2 Context Engineering (malloc/free metaphor)
- **What it does:** Prevents context pollution by starting each agent invocation from scratch. References a formal "Context Engineering" document explaining why single-task fresh context is superior.
- **How:** Each loop iteration renders a fresh prompt file and pipes/passes it to the agent CLI. No conversation history carries over between iterations. The reference document (`.agents/ralph/references/CONTEXT_ENGINEERING.md`) provides the theoretical framework.

### 1.3 Template Hierarchy
- **What it does:** Allows project-local overrides of the default templates.
- **How:** The CLI checks for `.agents/ralph/` in the current project first; falls back to bundled defaults shipped with the npm package. Reported to the user at startup ("Using local templates" vs "Using bundled templates").

### 1.4 State Separation
- **What it does:** Separates portable configuration (`.agents/ralph/`) from per-project runtime state (`.ralph/`).
- **How:** `.agents/ralph/` contains prompts, config, and references (copyable between repos). `.ralph/` contains progress logs, guardrails, error logs, activity logs, run logs, and temp files (gitignored, project-specific).

---

## 2. PRD (PRODUCT REQUIREMENTS DOCUMENT) SYSTEM

### 2.1 Interactive PRD Generation
- **What it does:** Generates a structured JSON PRD from a natural language description via an AI agent.
- **How:** `ralph prd "description"` or interactive prompt via `@clack/prompts`. Constructs a prompt instructing the agent to ask 5-10 clarifying questions, then produce JSON output. Supports `--out <path>` for custom output paths.

### 2.2 JSON PRD Format
- **What it does:** Defines a machine-readable project specification with stories, dependencies, quality gates, and metadata.
- **How:** JSON schema includes `version`, `project`, `overview`, `goals`, `nonGoals`, `successMetrics`, `openQuestions`, `stack`, `routes`, `uiNotes`, `dataModel`, `importFormat`, `rules`, `qualityGates`, and `stories[]`. Each story has `id`, `title`, `status`, `dependsOn`, `description`, `acceptanceCriteria`.

### 2.3 PRD Multi-File Support
- **What it does:** Supports multiple PRD files in `.agents/tasks/` with interactive selection.
- **How:** If multiple JSON files exist in `.agents/tasks/` and no `--prd` flag is given, uses `@clack/prompts` `select()` to let the user choose. Single file is auto-selected.

### 2.4 PRD Overview Generation
- **What it does:** Generates a human-readable overview markdown file from a JSON PRD.
- **How:** `ralph overview` reads the PRD JSON, counts stories by status (open/in_progress/done), lists quality gates, and writes a `prd-<slug>.overview.md` alongside the JSON file.

### 2.5 PRD Skill (Agent Prompt)
- **What it does:** Provides detailed instructions to the AI agent on how to create a good PRD.
- **How:** The `skills/prd/SKILL.md` instructs the agent to ask clarifying questions in batches of 5, always ask about quality gates, produce JSON with sequential US-XXX IDs, ensure stories are small enough for single iterations, include examples and negative cases in acceptance criteria.

---

## 3. STORY MANAGEMENT

### 3.1 Automatic Story Selection
- **What it does:** Picks the next actionable story based on status and dependency resolution.
- **How:** Python script (`select_story()`) reads the PRD JSON, finds the first `open` story whose `dependsOn` stories are all `done`. Uses `fcntl.flock()` for file locking to support concurrent access.

### 3.2 Story Status Lifecycle
- **What it does:** Tracks story states: `open` -> `in_progress` -> `done`.
- **How:** When selected, a story is marked `in_progress` with `startedAt` timestamp. On completion (agent outputs `<promise>COMPLETE</promise>`), marked `done` with `completedAt`. On failure or no completion signal, reset to `open`. All status updates include `updatedAt` timestamps.

### 3.3 Dependency Resolution
- **What it does:** Respects inter-story dependencies so stories execute in the correct order.
- **How:** Each story has a `dependsOn` array of story IDs. A story is only eligible for selection if all its dependencies have status `done`.

### 3.4 Stale Story Recovery
- **What it does:** Automatically reopens stories stuck in `in_progress` for too long (e.g., from crashed loops).
- **How:** Configurable `STALE_SECONDS` (default 0 = disabled). If set, the `select_story()` Python script checks `startedAt` timestamps and resets stale `in_progress` stories to `open`.

### 3.5 Concurrency Protection (File Locking)
- **What it does:** Prevents race conditions when multiple Ralph instances access the same PRD.
- **How:** Uses `fcntl.flock()` (exclusive lock) in both `select_story()` and `update_story_status()` Python functions when reading/writing the PRD JSON file. Falls back gracefully if `fcntl` is unavailable.

### 3.6 Completion Signal
- **What it does:** Determines whether an agent run successfully completed a story.
- **How:** The loop checks the agent's output log for the literal string `<promise>COMPLETE</promise>`. If found, story is marked `done`; otherwise, it is reset to `open`.

---

## 4. AGENT RUNNER SYSTEM

### 4.1 Multi-Agent Support
- **What it does:** Supports four different AI coding agents: Codex, Claude, Droid (Factory), and OpenCode.
- **How:** `agents.sh` defines both headless and interactive command templates for each agent. The `--agent` CLI flag or `DEFAULT_AGENT` config selects which to use.

### 4.2 Agent Command Templates
- **What it does:** Provides two modes per agent: headless (for build loops) and interactive (for PRD generation).
- **How:** Headless commands pipe/pass prompts via stdin or file. Interactive commands open the agent in a session mode. Templates use `{prompt}` placeholder for file paths.
  - **Codex:** `codex exec --yolo --skip-git-repo-check -` (headless) / `codex --yolo {prompt}` (interactive)
  - **Claude:** `claude -p --dangerously-skip-permissions "$(cat {prompt})"` (headless) / `claude --dangerously-skip-permissions {prompt}` (interactive)
  - **Droid:** `droid exec --skip-permissions-unsafe -f {prompt}` (headless) / `droid --skip-permissions-unsafe {prompt}` (interactive)
  - **OpenCode:** `opencode run "$(cat {prompt})"` (headless) / `opencode --prompt {prompt}` (interactive)

### 4.3 Agent Health Check (Ping)
- **What it does:** Verifies an agent CLI is installed and responsive.
- **How:** `ralph ping` sends the prompt "Reply with `<end>pong</end>` only." to the selected agent and checks the output for that exact string. Validates the agent binary exists first via `command -v`.

### 4.4 Agent Install Hints
- **What it does:** Provides installation instructions when an agent CLI is not found.
- **How:** When `require_agent()` fails to find the agent binary, it prints the appropriate install command (e.g., `npm i -g @openai/codex`, `curl -fsSL https://claude.ai/install.sh | bash`).

### 4.5 OpenCode Server Mode
- **What it does:** Supports faster performance with OpenCode via persistent server.
- **How:** Commented-out configuration in `agents.sh` for `--attach http://localhost:4096` flag, avoiding cold boot on every run.

---

## 5. PROMPT ENGINEERING

### 5.1 Build Prompt Template
- **What it does:** Constructs a detailed, structured prompt for each agent iteration with all necessary context.
- **How:** `PROMPT_build.md` is a Mustache-style template with `{{VAR}}` placeholders. The `render_prompt()` function (Python) substitutes paths, story details, quality gates, run metadata, and configuration flags into the template.

### 5.2 Injected Context
- **What it does:** Provides the agent with all the files and paths it needs to operate autonomously.
- **How:** The rendered prompt includes paths to: PRD, AGENTS.md, progress log, guardrails, guardrails reference, context engineering reference, error log, activity log, activity logger command, run ID, iteration number, run log path, and run summary path.

### 5.3 Structured Task Instructions
- **What it does:** Gives the agent a strict ordered workflow to follow.
- **How:** The prompt defines a 11-step procedure: read guardrails, read error log, read PRD, audit codebase, follow AGENTS.md, implement story, run verification, run build/dev, perform security/performance/regression audit, commit (if allowed), append progress entry.

### 5.4 Progress Entry Format
- **What it does:** Standardizes how the agent records its work.
- **How:** A strict markdown template for progress entries including: thread ID, run/iteration info, guardrails reviewed flag, commit hash, verification commands and results, files changed, implementation notes, and learnings for future iterations.

### 5.5 Non-Negotiable Rules
- **What it does:** Constrains agent behavior to prevent scope creep and common mistakes.
- **How:** Explicit rules in the prompt: implement only the selected story, do not ask questions, do not change unrelated code, do not assume -- read code first, no placeholders/stubs, do not edit the PRD JSON, commit all changes, perform security/performance/regression review before committing.

### 5.6 Browser Testing Requirement
- **What it does:** Mandates browser verification for frontend stories.
- **How:** The build prompt instructs: if the story changes UI, load the `dev-browser` skill, navigate to the page, verify changes, take screenshots. "A frontend story is NOT complete until browser verification passes."

---

## 6. GUARDRAILS SYSTEM ("Signs")

### 6.1 Persistent Guardrails
- **What it does:** Maintains a file of "lessons learned" that is read before every iteration.
- **How:** `.ralph/guardrails.md` is created with seed content (core signs: "Read Before Writing", "Test Before Commit") and loaded into every agent prompt. Agents are instructed to add new signs when they encounter repeated failures.

### 6.2 Signs Metaphor
- **What it does:** Provides a framework for categorizing and creating guardrails.
- **How:** Reference document (`.agents/ralph/references/GUARDRAILS.md`) defines four sign types: Preventive, Corrective, Process, and Architecture. Each sign has Trigger, Instruction, Added-after, and optional Example fields.

### 6.3 Sign Lifecycle Management
- **What it does:** Guides creation, refinement, and retirement of guardrails.
- **How:** The reference document explains: add after same mistake happens twice, refine if not working (make trigger more specific), retire when underlying issue is fixed at a deeper level.

### 6.4 Error Log Integration
- **What it does:** Tracks repeated failures separately from guardrails.
- **How:** `.ralph/errors.log` records iteration failures with timestamps. The agent is instructed to read this before starting work and to add new entries when errors occur. Persistent errors should be promoted to guardrails.

---

## 7. LOGGING AND OBSERVABILITY

### 7.1 Activity Log
- **What it does:** Records timestamped events for every iteration.
- **How:** `.ralph/activity.log` with `[YYYY-MM-DD HH:MM:SS] message` format. Written by both the loop shell script (iteration start/end) and the agent (via the activity logger command). Has a "Run Summary" section for quick overview.

### 7.2 Activity Logger (Helper Script)
- **What it does:** Provides a simple CLI for agents to log activity.
- **How:** `log-activity.sh` (or `ralph log "message"` via CLI) appends timestamped messages to the activity log. Agents are instructed to log: start of work, major code changes, tests/verification, and progress log updates.

### 7.3 Per-Run Log Files
- **What it does:** Captures complete agent output for each iteration.
- **How:** Agent stdout/stderr is piped through `tee` to `.ralph/runs/run-<tag>-iter-<n>.log`. Each run also gets a `.md` summary file.

### 7.4 Run Summary Metadata
- **What it does:** Records structured metadata about each iteration.
- **How:** `write_run_meta()` creates a markdown file with: Run ID, iteration number, mode, story, start/end times, duration, status, log file path, git head before/after, commits made, changed files, and uncommitted changes.

### 7.5 Run Summary Aggregation
- **What it does:** Appends a one-line summary to the activity log's "Run Summary" section.
- **How:** `append_run_summary()` (Python) inserts a formatted line (timestamp, run tag, iteration, mode, story, duration, status) right after the "## Run Summary" header.

### 7.6 Progress Log
- **What it does:** Append-only log of what was accomplished across iterations.
- **How:** `.ralph/progress.md` is initialized with a header and "Codebase Patterns" section. Each agent iteration appends a structured progress entry (per the template). Includes a "Learnings for future iterations" section for knowledge transfer between iterations.

---

## 8. GIT INTEGRATION

### 8.1 Auto-Commit Behavior
- **What it does:** Agents commit their own changes as part of the loop.
- **How:** The build prompt instructs agents to `git add -A` and commit using the `$commit` skill. The loop checks for uncommitted changes after each iteration and logs a warning if any remain.

### 8.2 No-Commit Mode
- **What it does:** Allows dry-run iterations without git commits.
- **How:** `--no-commit` CLI flag sets `NO_COMMIT=true`, injected into the prompt as `{{NO_COMMIT}}`. The prompt instructs: "If No-commit is true, do NOT commit or push changes."

### 8.3 Git Diff Tracking
- **What it does:** Records what changed in each iteration at the git level.
- **How:** `git_head()` captures HEAD before/after each iteration. `git_commit_list()` and `git_changed_files()` compute the diff. `git_dirty_files()` reports any uncommitted changes. All are recorded in the run summary.

### 8.4 Commit Skill
- **What it does:** Provides structured commit message guidelines (Conventional Commits format).
- **How:** `skills/commit/SKILL.md` defines: commit types (feat/fix/refactor/perf/test/ci/docs/chore/style/security), required scope in kebab-case, 50-char subject line limit, present tense imperative verbs, body format for complex changes, git trailers, breaking change conventions. Also covers PR creation format.

---

## 9. SKILLS SYSTEM

### 9.1 Skill Installation
- **What it does:** Installs agent-specific skills (commit, dev-browser, prd) to the appropriate directory.
- **How:** `ralph install --skills` prompts for agent type and scope (local/global), then copies skill directories to the correct path:
  - Codex: `.codex/skills/`
  - Claude: `.claude/skills/`
  - Droid: `.factory/skills/`
  - OpenCode: `.local/share/opencode/skills/` or `.opencode/skills/`

### 9.2 Dev-Browser Skill
- **What it does:** Provides browser automation for testing frontend changes.
- **How:** A full Playwright-based browser automation system with: standalone and extension modes, persistent page state, ARIA snapshot accessibility tree inspection, screenshot capture, named page management, heredoc script execution via `npx tsx`. Includes a relay server for Chrome extension mode.

### 9.3 PRD Skill
- **What it does:** Guides the AI agent in generating well-structured PRDs.
- **How:** Detailed SKILL.md with instructions for: asking clarifying questions, JSON schema specification, story sizing guidance, dependency ordering, quality gate inclusion, example/negative case requirements.

---

## 10. CLI FEATURES

### 10.1 Command Structure
- **What it does:** Provides a clean CLI with multiple commands.
- **How:** Node.js entry point (`bin/ralph`) parses args manually, supports: `install`, `prd`, `ping`, `log`, `build`, `overview`, `help`. Uses `@clack/prompts` for interactive UI elements.

### 10.2 Auto-Update Check
- **What it does:** Checks for newer versions on npm and offers to update.
- **How:** On every CLI invocation (if TTY), runs `npm view @iannuttall/ralph version`, compares with installed version using `compareVersions()`, and prompts to update if newer. Skippable via `RALPH_SKIP_UPDATE_CHECK=1`.

### 10.3 Interactive Prompts
- **What it does:** Provides polished interactive UI for selections and confirmations.
- **How:** Uses `@clack/prompts` library for: PRD file selection, update confirmation, skill installation agent/scope selection, PRD description input.

### 10.4 Dry-Run Mode
- **What it does:** Allows testing the loop without invoking real agents.
- **How:** `RALPH_DRY_RUN=1` environment variable skips agent execution, creates stub PRD files, and exits cleanly. Used in the test suite.

---

## 11. CONFIGURATION

### 11.1 Config File
- **What it does:** Allows overriding all default paths and settings.
- **How:** `.agents/ralph/config.sh` is sourced by `loop.sh`. Supports overriding: `PRD_PATH`, `PROGRESS_PATH`, `GUARDRAILS_PATH`, `ERRORS_LOG_PATH`, `ACTIVITY_LOG_PATH`, `TMP_DIR`, `RUNS_DIR`, `GUARDRAILS_REF`, `CONTEXT_REF`, `ACTIVITY_CMD`, `AGENT_CMD`, `MAX_ITERATIONS`, `NO_COMMIT`, `STALE_SECONDS`, `AGENTS_PATH`, `PROMPT_BUILD`.

### 11.2 CLI Flag Overrides
- **What it does:** Allows per-run overrides without changing config files.
- **How:** `--prd <path>`, `--progress <path>`, `--agent <name>`, `--no-commit` flags on the CLI. Environment variables (`PRD_PATH`, `PROGRESS_PATH`, `AGENT_CMD`) also override defaults.

### 11.3 Path Resolution
- **What it does:** Handles both relative and absolute paths consistently.
- **How:** `abs_path()` function resolves relative paths against `ROOT_DIR`. `RALPH_ROOT` environment variable allows the CLI to set the project root independently of the script location.

---

## 12. ERROR HANDLING

### 12.1 Agent Failure Recovery
- **What it does:** Handles agent crashes gracefully and resets story state.
- **How:** Agent exit code is captured via `set +e`. Non-zero exit resets the story to `open`, logs the error, and continues to the next iteration. Exit codes 130/143 (SIGINT/SIGTERM) cause immediate exit.

### 12.2 Uncommitted Change Detection
- **What it does:** Warns when an agent leaves uncommitted changes.
- **How:** After each iteration, `git_dirty_files()` checks `git status --porcelain`. If dirty files exist and `NO_COMMIT=false`, an error is logged to `errors.log` with a reference to the run summary.

### 12.3 PRD Parse Error Handling
- **What it does:** Gracefully handles malformed PRD JSON.
- **How:** The `select_story()` Python script catches JSON parse errors and writes a structured error response. The loop checks the `ok` field and reports meaningful messages.

### 12.4 Missing Agent Detection
- **What it does:** Fails early with helpful messages when the required agent is not installed.
- **How:** `require_agent()` checks `command -v` for the agent binary before starting the loop, then prints install instructions if missing.

---

## 13. TESTING

### 13.1 CLI Smoke Tests
- **What it does:** Verifies basic CLI functionality without requiring agents.
- **How:** `tests/cli-smoke.mjs` runs: `ralph --help`, `ralph prd` (with `RALPH_DRY_RUN=1`), `ralph overview`, and checks output files exist.

### 13.2 Agent Loop Smoke Tests
- **What it does:** Tests the loop for each supported agent in dry-run mode.
- **How:** `tests/agent-loops.mjs` creates temp projects with a PRD, runs `ralph build 1 --no-commit --agent=<name>` with `RALPH_DRY_RUN=1` for codex, claude, and droid.

### 13.3 Agent Ping Tests
- **What it does:** Verifies real agents are responsive.
- **How:** `tests/agent-ping.mjs` runs `ralph ping --agent=<name>` for each installed agent, skipping those not found.

### 13.4 Real Agent Integration Tests
- **What it does:** Runs a full end-to-end loop with real agents.
- **How:** `tests/real-agents.mjs` creates a temp project with two dependent stories (create a file, then create a second file), runs `ralph build 2`, then asserts: all stories are `done`, at least one git commit exists, and progress log was created.

---

## 14. FEATURES NOTABLY ABSENT (compared to what portableralph might have)

Based on this analysis, iannuttall/ralph does **not** have:
- **Model/provider selection** (e.g., choosing between GPT-4, Claude Sonnet, etc.) -- it delegates entirely to the agent CLI
- **Desktop notifications** (no notification system)
- **Plan mode** (explicitly removed: `ralph plan` prints an error saying "Use `ralph build` with a JSON PRD")
- **Token/cost tracking**
- **Concurrency at the iteration level** (runs one agent at a time, though file locking supports multiple Ralph instances on the same PRD)
- **Session management** beyond the iteration loop (each iteration is fully independent)
- **Custom model parameters** (temperature, max tokens, etc.)
- **SSRF protection or URL validation**
- **Rate limiting**
agentId: a5671bb (for resuming to continue this agent's work if needed)
<usage>total_tokens: 55119
tool_uses: 37
duration_ms: 258610</usage>

The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.

>ps aux | grep -E 'ralph|claude' | grep -v grep

jc        940763  0.0  0.0   8016  4096 pts/0    S+   11:31   0:00 /bin/bash /mnt/dest-btrfs/home/jc/ralph/ralph.sh plan.md plan
jc        940792  0.0  0.0   8016  2316 pts/0    S+   11:31   0:00 /bin/bash /mnt/dest-btrfs/home/jc/ralph/ralph.sh plan.md plan
jc        940793 99.9  0.0   9004  5116 pts/0    R+   11:31   2:16 /bin/bash /mnt/dest-btrfs/home/jc/ralph/notify.sh :rocket: *Ralph Started*\n```Plan: plan\nMode: plan\nRepo: mage``` :rocket:
jc        940936 26.1  1.4 74712368 467332 pts/3 Rl+  11:32   0:23 claude

>ps aux | grep -E 'ralph|notify' | grep -v grep

jc        940763  0.0  0.0   8016  4096 pts/0    S+   11:31   0:00 /bin/bash /mnt/dest-btrfs/home/jc/ralph/ralph.sh plan.md plan
jc        942595  0.0  0.0   8016  2328 pts/0    S+   11:35   0:00 /bin/bash /mnt/dest-btrfs/home/jc/ralph/ralph.sh plan.md plan
jc        942596  0.0  0.0   8416  4608 pts/0    S+   11:35   0:00 /bin/bash /mnt/dest-btrfs/home/jc/ralph/notify.sh :rocket: *Ralph Started*\n```Plan: plan\nMode: plan\nRepo: mage``` :rocket:
jc        942607  0.0  0.0   8416  2936 pts/0    S+   11:35   0:00 /bin/bash /mnt/dest-btrfs/home/jc/ralph/notify.sh :rocket: *Ralph Started*\n```Plan: plan\nMode: plan\nRepo: mage``` :rocket:

>ps aux | grep -i claude | grep -v grep

jc        940936 20.1  1.6 74712368 521772 pts/3 Sl+  11:32   0:10 claude

>ls -la /tmp/tmp.* 2>/dev/null | tail -20

-rw------- 1 jc jc 0 Feb 15 11:35 /tmp/tmp.kaPSwDEaDM
-rw------- 1 jc jc 0 Feb 15 11:35 /tmp/tmp.nyJpBNqVZi

>git status

On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   notify.sh
	modified:   ralph.sh
	modified:   setup-notifications.sh

no changes added to commit (use "git add" and/or "git commit -a")

>git diff

diff --git a/notify.sh b/notify.sh
index 1b6b8b8..c89a767 100755
--- a/notify.sh
+++ b/notify.sh
@@ -78,9 +78,9 @@ fi
 # Load and decrypt environment variables
 if [ -f "$RALPH_DIR/decrypt-env.sh" ]; then
     source "$RALPH_DIR/decrypt-env.sh"
-    if ! decrypt_ralph_env 2>&1 | grep -q "^Error:"; then
-        : # Decryption succeeded or no encrypted values
-    else
+    # Call decrypt_ralph_env directly to allow variable updates
+    # Don't pipe the output which would run in a subshell
+    if ! decrypt_ralph_env; then
         # Only show warning in test mode, otherwise notifications might spam
         if [ "${1:-}" = "--test" ]; then
             echo "Warning: Failed to decrypt some environment variables" >&2
@@ -268,13 +268,15 @@ send_discord() {
     local username="${RALPH_DISCORD_USERNAME:-Ralph}"
     local avatar_url="${RALPH_DISCORD_AVATAR_URL:-}"
 
-    # Convert Slack-style formatting to Discord markdown safely
-    # Avoid sed for user input - use bash substitution
-    local discord_msg="$msg"
-    # Replace *text* with **text** for Discord bold
-    while [[ "$discord_msg" =~ \*([^*]+)\* ]]; do
-        discord_msg="${discord_msg/\*${BASH_REMATCH[1]}\*/**${BASH_REMATCH[1]}**}"
+    # Convert Slack-style *bold* to Discord **bold** in a single left-to-right pass
+    # (A while loop replacing *x* with **x** loops forever since **x** still matches *x*)
+    local discord_msg=""
+    local remaining="$msg"
+    while [[ "$remaining" =~ ^([^*]*)\*([^*]+)\*(.*) ]]; do
+        discord_msg+="${BASH_REMATCH[1]}**${BASH_REMATCH[2]}**"
+        remaining="${BASH_REMATCH[3]}"
     done
+    discord_msg+="$remaining"
 
     local payload
     if command -v jq &> /dev/null; then
@@ -1214,7 +1216,7 @@ if ! $TEST_MODE; then
 fi
 
 # Track errors for better reporting
-declare -A SEND_ERRORS
+declare -A SEND_ERRORS=()
 
 # Send to all configured platforms with individual error tracking
 if ! send_slack "$MESSAGE"; then
@@ -1244,7 +1246,8 @@ if $TEST_MODE; then
     echo ""
     if $SENT_ANY; then
         echo "Test complete! Check your notification channels."
-        if [ ${#SEND_ERRORS[@]} -gt 0 ]; then
+        # Check if SEND_ERRORS has any elements
+        if [ ${#SEND_ERRORS[@]} -gt 0 ] 2>/dev/null; then
             echo ""
             echo "Note: Some platforms failed to send. Check configuration."
         fi
diff --git a/ralph.sh b/ralph.sh
index 9230776..7c901f2 100755
--- a/ralph.sh
+++ b/ralph.sh
@@ -111,7 +111,18 @@ RALPH_CONFIG_FILE="${USER_HOME}/.ralph.env"
 if [ -f "$RALPH_CONFIG_FILE" ] && validate_config "$RALPH_CONFIG_FILE"; then
     source "$RALPH_CONFIG_FILE"
 
-    # Validate loaded configuration values
+    # Decrypt encrypted environment variables BEFORE validation
+    if [ -f "$RALPH_DIR/decrypt-env.sh" ]; then
+        source "$RALPH_DIR/decrypt-env.sh"
+        # Call decrypt_ralph_env directly to allow variable updates
+        # Capture any errors but don't pipe the output (which would run in a subshell)
+        if ! decrypt_ralph_env; then
+            echo -e "${YELLOW}Warning: Failed to decrypt some environment variables${NC}" >&2
+            echo "Some notification platforms may not work correctly" >&2
+        fi
+    fi
+
+    # Validate loaded configuration values (now with decrypted values)
     if [ -n "${RALPH_SLACK_WEBHOOK_URL:-}" ]; then
         if ! validate_webhook_url "$RALPH_SLACK_WEBHOOK_URL" "RALPH_SLACK_WEBHOOK_URL"; then
             echo -e "${YELLOW}Warning: Invalid RALPH_SLACK_WEBHOOK_URL, disabling Slack notifications${NC}" >&2
@@ -153,17 +164,6 @@ if [ -f "$RALPH_CONFIG_FILE" ] && validate_config "$RALPH_CONFIG_FILE"; then
     fi
 fi
 
-# Decrypt encrypted environment variables
-if [ -f "$RALPH_DIR/decrypt-env.sh" ]; then
-    source "$RALPH_DIR/decrypt-env.sh"
-    if ! decrypt_ralph_env 2>&1 | grep -q "^Error:"; then
-        : # Decryption succeeded or no encrypted values
-    else
-        echo -e "${YELLOW}Warning: Failed to decrypt some environment variables${NC}" >&2
-        echo "Run 'ralph notify setup' if you have notification issues" >&2
-    fi
-fi
-
 VERSION="1.7.0"
 
 # Auto-commit setting (default: true)
@@ -171,6 +171,10 @@ VERSION="1.7.0"
 # Or by adding DO_NOT_COMMIT on its own line in the plan file
 RALPH_AUTO_COMMIT="${RALPH_AUTO_COMMIT:-true}"
 
+# Model setting (default: sonnet)
+# Can be set via: export RALPH_MODEL="claude-opus-4-6" in ~/.ralph.env
+RALPH_MODEL="${RALPH_MODEL:-sonnet}"
+
 # Check if plan file contains DO_NOT_COMMIT directive
 # Skips content inside ``` code blocks to avoid false positives
 should_skip_commit_from_plan() {
@@ -547,6 +551,7 @@ echo -e "  Plan:      ${YELLOW}$PLAN_FILE${NC}"
 echo -e "  Mode:      ${YELLOW}$MODE${NC}"
 echo -e "  Progress:  ${YELLOW}$PROGRESS_FILE${NC}"
 [ "$MAX_ITERATIONS" -gt 0 ] && echo -e "  Max Iter:  ${YELLOW}$MAX_ITERATIONS${NC}"
+echo -e "  Model:     ${YELLOW}$RALPH_MODEL${NC}"
 if [ "$SHOULD_COMMIT" = "true" ]; then
     echo -e "  Commit:    ${GREEN}enabled${NC}"
 else
@@ -719,18 +724,11 @@ while true; do
         }
         chmod 600 "$claude_output_file" "$claude_error_file"
 
-        # Run Claude
+        # Run Claude (stream output to terminal via tee while capturing to file)
         echo "$PROMPT" | claude -p \
             --dangerously-skip-permissions \
-            --model sonnet \
-            --verbose > "$claude_output_file" 2>"$claude_error_file" || claude_exit_code=$?
-
-        # Display output on first attempt or final retry
-        if [ $claude_attempt -eq 1 ] || [ $claude_attempt -eq $max_claude_retries ]; then
-            if [ -f "$claude_output_file" ]; then
-                cat "$claude_output_file"
-            fi
-        fi
+            --model "$RALPH_MODEL" \
+            --verbose 2>"$claude_error_file" | tee "$claude_output_file" || claude_exit_code=$?
 
         # Capture any error output
         claude_errors=""
diff --git a/setup-notifications.sh b/setup-notifications.sh
index c0ed2f1..eee303f 100755
--- a/setup-notifications.sh
+++ b/setup-notifications.sh
@@ -580,7 +580,6 @@ echo "" >> "$CONFIG_FILE"
 
 if [ -n "$SLACK_URL" ]; then
     echo "# Slack" >> "$CONFIG_FILE"
-    local encrypted_slack
     encrypted_slack=$(encrypt_value "$SLACK_URL")
     echo "export RALPH_SLACK_WEBHOOK_URL=\"$encrypted_slack\"" >> "$CONFIG_FILE"
     echo "" >> "$CONFIG_FILE"
@@ -588,7 +587,6 @@ fi
 
 if [ -n "$DISCORD_URL" ]; then
     echo "# Discord" >> "$CONFIG_FILE"
-    local encrypted_discord
     encrypted_discord=$(encrypt_value "$DISCORD_URL")
     echo "export RALPH_DISCORD_WEBHOOK_URL=\"$encrypted_discord\"" >> "$CONFIG_FILE"
     echo "" >> "$CONFIG_FILE"
@@ -596,8 +594,6 @@ fi
 
 if [ -n "$TELEGRAM_TOKEN" ]; then
     echo "# Telegram" >> "$CONFIG_FILE"
-    local encrypted_token
-    local encrypted_chat
     encrypted_token=$(encrypt_value "$TELEGRAM_TOKEN")
     encrypted_chat=$(encrypt_value "$TELEGRAM_CHAT")
     echo "export RALPH_TELEGRAM_BOT_TOKEN=\"$encrypted_token\"" >> "$CONFIG_FILE"
@@ -611,7 +607,7 @@ if [ -n "$EMAIL_TO" ]; then
     echo "export RALPH_EMAIL_FROM=\"$EMAIL_FROM\"" >> "$CONFIG_FILE"
 
     if [ "$EMAIL_METHOD" = "smtp" ]; then
-        local encrypted_pass
+        encrypted_pass
         encrypted_pass=$(encrypt_value "$SMTP_PASS")
         echo "export RALPH_SMTP_HOST=\"$SMTP_HOST\"" >> "$CONFIG_FILE"
         echo "export RALPH_SMTP_PORT=\"$SMTP_PORT\"" >> "$CONFIG_FILE"
@@ -619,11 +615,11 @@ if [ -n "$EMAIL_TO" ]; then
         echo "export RALPH_SMTP_PASSWORD=\"$encrypted_pass\"" >> "$CONFIG_FILE"
         echo "export RALPH_SMTP_TLS=\"true\"" >> "$CONFIG_FILE"
     elif [ "$EMAIL_METHOD" = "sendgrid" ]; then
-        local encrypted_key
+        encrypted_key
         encrypted_key=$(encrypt_value "$SENDGRID_KEY")
         echo "export RALPH_SENDGRID_API_KEY=\"$encrypted_key\"" >> "$CONFIG_FILE"
     elif [ "$EMAIL_METHOD" = "ses" ]; then
-        local encrypted_secret
+        encrypted_secret
         encrypted_secret=$(encrypt_value "$AWS_SECRET")
         echo "export RALPH_AWS_SES_REGION=\"$AWS_REGION\"" >> "$CONFIG_FILE"
         echo "export RALPH_AWS_ACCESS_KEY_ID=\"$AWS_KEY\"" >> "$CONFIG_FILE"
@@ -632,8 +628,8 @@ if [ -n "$EMAIL_TO" ]; then
 
     # Email options
     echo "export RALPH_EMAIL_HTML=\"true\"" >> "$CONFIG_FILE"
-    local batch_delay="${EMAIL_BATCH_DELAY_DEFAULT:-300}"
-    local batch_max="${EMAIL_BATCH_MAX_DEFAULT:-10}"
+    batch_delay="${EMAIL_BATCH_DELAY_DEFAULT:-300}"
+    batch_max="${EMAIL_BATCH_MAX_DEFAULT:-10}"
     echo "export RALPH_EMAIL_BATCH_DELAY=\"$batch_delay\"  # $(($batch_delay / 60)) minutes" >> "$CONFIG_FILE"
     echo "export RALPH_EMAIL_BATCH_MAX=\"$batch_max\"" >> "$CONFIG_FILE"
     echo "" >> "$CONFIG_FILE"

>git log --oneline -5

e529f84 Remove unnecessary security theater
cfdc9e7 doc: Add test verification evidence - all 10 suites confirmed passing
41fe489 fix: SSRF protection - properly reject localhost URLs
99e2d3e Fix: Remove 'local' keyword outside function (bash error)
d1078e5 Fix all test failures - 10/10 suites passing

>git add notify.sh ralph.sh setup-notifications.sh

(empty result)

>git commit -m "$(cat <<'EOF'
Fix infinite loop in Discord notification and stream Claude output

- Fix notify.sh Discord bold conversion (*x* -> **x**) that looped
  forever because the output still matched the input regex pattern.
  Replace with single-pass left-to-right processing.
- Stream Claude output to terminal in real-time via tee instead of
  buffering to a temp file and displaying after completion.
- Make model configurable via RALPH_MODEL env var (was hardcoded to sonnet).
- Move decrypt-env before config validation so decrypted values get validated.
- Fix 'local' keyword used outside functions in setup-notifications.sh.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

[master 6a520a1] Fix infinite loop in Discord notification and stream Claude output
 3 files changed, 39 insertions(+), 42 deletions(-)

>git status

On branch master
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

>git log master --oneline -5

6a520a1 Fix infinite loop in Discord notification and stream Claude output
e529f84 Remove unnecessary security theater
cfdc9e7 doc: Add test verification evidence - all 10 suites confirmed passing
41fe489 fix: SSRF protection - properly reject localhost URLs
99e2d3e Fix: Remove 'local' keyword outside function (bash error)

>git remote -v

origin	https://github.com/aaron777collins/portableralph.git (fetch)
origin	https://github.com/aaron777collins/portableralph.git (push)