drydock-cli 2.6.70__tar.gz → 2.6.74__tar.gz

drydock_cli-2.6.74/.auto_release.lock

@@ -0,0 +1 @@
+962444

drydock_cli-2.6.74/MODEL_SHORTCOMINGS.md

@@ -0,0 +1,224 @@
+# Gemma 4 26B-A4B Shortcomings Log
+
+Running list of model-level limitations observed in real drydock use, with
+concrete evidence. Intent: inform future LoRA fine-tuning + Deep Noir
+steering datasets. Each entry is a pattern, NOT a one-off bug.
+
+Last updated: 2026-04-12
+
+---
+
+## 1. Catastrophic tool-arg malformation → destructive side effects
+
+**Pattern:** Model sends `search_replace` with `content` + `new_string` keys
+but no `search` / `old_string`. Drydock's raw-code-fallback (before my fix)
+overwrote entire files with fragments.
+
+**Evidence:** ACE v1 cli.py nuked from 5171 chars → 16-char fragment. Session
+`20260412_162052_ee34fefb` msg #61. Lost 120 lines of working code.
+
+**Candidate training signal:**
+- Positive: model sends `{search: "...", replace: "..."}` or proper
+  `<<<<<<< SEARCH` blocks.
+- Negative: model sends raw code in `content` expecting a file overwrite.
+
+**Harness mitigation already in place:** refuse overwrites that shrink file
+by >50%. Still, the model should learn to format tool calls correctly.
+
+---
+
+## 2. Scaffolding without wiring
+
+**Pattern:** Model adds a new parameter to a public function's signature +
+adds the implementation in the callee, but doesn't update the intermediate
+call site that connects them. Tests pass for surface checks (signature
+inspection) but the feature is non-functional at runtime.
+
+**Evidence:**
+- tabulate `row_count_in_header`: added to `tabulate()` signature and to
+  `_format_table()` logic, but `tabulate()` never passes the new arg to
+  `_format_table()`. Feature non-functional; tests pass because the test
+  just checked the signature.
+- Session: `session_20260412_105528_30d43609`.
+
+**Root cause hypothesis:** Model doesn't trace execution path end-to-end.
+Treats each file as independent.
+
+**Candidate training signal:** Traces where model correctly chases a
+parameter through the full call graph vs traces where it stops at surface.
+
+---
+
+## 3. Subtle logic bugs undiagnosed after N iterations
+
+**Pattern:** Model produces plausible-looking code with a subtle bug.
+Running tests fails. Model tries rewriting the whole file rather than
+tracing the specific failure.
+
+**Evidence:**
+- **mini_db parser**: `_parse_select_body()` consumed `WHERE` as a table
+  alias because alias detection only excluded `JOIN` from the list of
+  SQL keywords. Fix was one line. Model made 4 iterations (~20 min)
+  without finding it.
+- **tool_agent log whitelist**: `if self.verbose or level in ["THINK",
+  "PLAN", "TOOL"]:` — missing `"ANSWER"`. One-character fix. Model ran
+  3 iterations without finding it.
+
+**Common trait:** Bug is in a data structure / enum / list that the model
+didn't reason about. It could SEE the line but didn't mentally trace
+which levels were allowed.
+
+**Candidate training signal:** Worked examples of "run the failing test,
+identify the exact line that produces wrong output, trace the data flow,
+fix only that line."
+
+---
+
+## 4. Inheritance blindness across packages
+
+**Pattern:** When a class inherits from a parent in a different package,
+the model looks for attributes/methods in the child class's file. Doesn't
+think to follow the inheritance chain to the parent package.
+
+**Evidence:**
+- **Flask `request.is_xml`**: Model read `src/flask/wrappers.py` 13 times
+  looking for `is_json` to pattern-match from. But `is_json` is in
+  werkzeug's `Request` (parent class). Model gave up without writing
+  anything. With an explicit hint in the task ("is_json is in werkzeug"),
+  model solved it in 61s.
+
+**Candidate training signal:** Traces where model correctly uses grep to
+find a name in parent-class packages (`grep -r "def is_json" site-packages/`)
+vs traces where it re-reads the same file.
+
+---
+
+## 5. Regression during targeted fixes
+
+**Pattern:** Asked to fix failure X, model rewrites unrelated passing code
+and breaks it. Advisory "don't break passing tests" in prompt doesn't help.
+
+**Evidence:**
+- **site_gen**: 4/5 tests passing. Asked to fix the 5th (title render).
+  Model rewrote the template engine from scratch, lost 4 passing tests
+  → 0/5. Required manual rollback.
+- This happened repeatedly until I added rollback to ralph_loop.
+
+**Harness mitigation:** Auto-rollback on score regression (snapshot before,
+restore if tests go down). Critical safety net.
+
+**Candidate training signal:** Traces with minimal targeted patches
+(`search_replace` with 3-line blocks) vs traces with full-file rewrites.
+
+---
+
+## 6. Blindness to own stuckness
+
+**Pattern:** Model rewrites the same file multiple times identically when
+tests fail. Doesn't recognize the rewrites aren't helping; doesn't try a
+different approach. When dedup block fires after 3 identical writes,
+sometimes workaround by renaming the file (e.g. `feedback_new.py`).
+
+**Evidence:**
+- ACE v1 session msg #23, #25, #27: three identical writes of `feedback.py`.
+  Then msg #29: renamed to `feedback_new.py` to bypass dedup.
+- mini_db: 100 search_replace calls, 65 failed. Model kept trying the
+  same pattern instead of switching approaches.
+
+**Candidate training signal:** Traces where model after N failed attempts
+tries: `bash` to run the failing command, `web_search` for the error,
+`read_file` on a different related file, or explicitly changes approach.
+
+---
+
+## 7. Doesn't use web_search even when enabled
+
+**Pattern:** Model has `web_search` tool available but doesn't reach for
+it when stuck, even for standard errors that have obvious online solutions.
+
+**Evidence:**
+- mini_db session (after web tools were enabled): 100 search_replace fails,
+  0 web_search calls. Model stayed in local-only failure loop.
+
+**Mitigation attempted:** `gemma4.md` prompt now explicitly says "use
+web_search when stuck 2+ iterations on same error." Need to verify it
+actually happens in practice.
+
+**Candidate training signal:** Strong — positive examples of "tried X,
+failed, googled error, found answer, fixed" vs "tried X 5x, never googled."
+
+---
+
+## 8. Hallucinated tool names
+
+**Pattern:** Model calls tool names that don't exist, e.g.
+`ralph_repo_index`, `list_mcp_resources`, `repo_index`.
+
+**Evidence:** mini_db v1 session called `ralph_repo_index` 5 times. Each
+returned "Unknown tool" error. Model kept trying.
+
+**Harness mitigation:** `_IGNORE_TOOLS` list silently drops known
+hallucinations to reduce error spam.
+
+**Candidate training signal:** Ground all tool calls to only names that
+exist in the current tool list.
+
+---
+
+## 9. Empty response / thinking stall
+
+**Pattern:** After a tool result, model generates `[thinking]` tokens but
+no `content` or `tool_calls` — returns an empty assistant message. Appears
+idle to the harness.
+
+**Evidence:** ACE v2 iter 5 "idle" status at 966s with no message activity.
+Also observed in earlier 5-min tier runs pre-fix.
+
+**Harness mitigation:** `_truncate_old_tool_results` in agent_loop +
+thinking-stall nudge. Partial fix — still observed in harder PRDs.
+
+**Candidate training signal:** Eliminate empty assistant responses. Every
+response should either have `content` or `tool_calls`.
+
+---
+
+## 10. Weak reasoning about performance / abstract tasks
+
+**Pattern:** Optimization phase of comprehensive_loop consistently fails
+("idle" status). Code review phase also struggles. These phases require
+abstract reasoning about hotspots, trade-offs, priorities.
+
+**Evidence:** comp_loop across 3 packages:
+- doc_qa: 9/9 phases passed (including optimize — simple PRD)
+- stock_screener: 8/9 (optimize failed — went idle)
+- tool_agent: 5/9 (multiple phases failed, optimize was one)
+
+**Candidate training signal:** Traces of optimization reasoning:
+"Profile showed X is hot; it's O(n²); rewrite as O(n log n); measure."
+Currently the model treats "optimize" as too vague.
+
+---
+
+## Harness / tooling shortcomings (non-model, but relevant)
+
+These are harness bugs I found — fixing them made the model LOOK better:
+
+- A. `search_replace` destructive overwrite (FIXED v2.6.67)
+- B. `write_file` didn't catch bare `raise` (FIXED v2.6.69)
+- C. `builder` subagent missing `web_search`/`web_fetch` (FIXED v2.6.71)
+- D. `_IGNORE_TOOLS` missing common hallucinations (FIXED v2.6.71)
+- E. ralph_loop false-positive baseline → wrong prompt (FIXED v2.6.71)
+
+---
+
+## Scoring suggested for training dataset
+
+Label each trace-step with outcome:
+- `good`: tool call succeeded + moved toward passing tests
+- `regression`: broke a previously-passing test
+- `wasted`: no progress on pass rate
+- `stuck`: repeated same action N times with no change
+- `recovered`: was stuck, used web_search/web_fetch/read_file to unblock
+
+Fine-tune on `good` and `recovered`. Filter out `wasted` and the parts of
+traces after a `regression` or `stuck` episode.

{drydock_cli-2.6.70 → drydock_cli-2.6.74}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 2.6.70
+Version: 2.6.74
 Summary: Local-first CLI coding agent — tested with Gemma 4 26B via vLLM
 Project-URL: Homepage, https://github.com/fbobe321/drydock
 Project-URL: Repository, https://github.com/fbobe321/drydock

{drydock_cli-2.6.70 → drydock_cli-2.6.74}/drydock/core/agents/models.py

@@ -202,7 +202,8 @@ DIAGNOSTIC = AgentProfile(
     agent_type=AgentType.SUBAGENT,
     max_turns=80,
     overrides={
-        "enabled_tools": ["grep", "read_file", "bash", "glob"],
+        "enabled_tools": ["grep", "read_file", "bash", "glob",
+                          "web_search", "web_fetch"],
         "system_prompt_id": "diagnostic",
     },
 )
@@ -242,12 +243,17 @@ BUILDER = AgentProfile(
         "enabled_tools": [
             "read_file", "write_file", "search_replace",
             "glob", "grep", "bash",
+            # web tools — when stuck on a difficult problem, the model can
+            # google for examples, error-message solutions, or API docs.
+            "web_search", "web_fetch",
         ],
         "system_prompt_id": "builder",
         "tools": {
             "write_file": {"permission": "always"},
             "search_replace": {"permission": "always"},
             "bash": {"permission": "always"},
+            "web_search": {"permission": "always"},
+            "web_fetch": {"permission": "always"},
         },
     },
 )

{drydock_cli-2.6.70 → drydock_cli-2.6.74}/drydock/core/llm/format.py

@@ -174,7 +174,13 @@ class APIToolFormatHandler:
 
         # Tools the model hallucinates that should be silently ignored
         # rather than generating a visible error that confuses the user.
-        _IGNORE_TOOLS = {"exit_plan_mode", "enter_plan_mode", "plan_mode"}
+        _IGNORE_TOOLS = {
+            "exit_plan_mode", "enter_plan_mode", "plan_mode",
+            # Gemma 4 confabulated tools — observed in user sessions and
+            # mini_db fresh build (called ralph_repo_index 5 times).
+            "ralph_repo_index", "repo_index", "index_repo",
+            "list_mcp_resources", "list_resources", "search_resources",
+        }
 
         for parsed_call in parsed.tool_calls:
             tool_class = active_tools.get(parsed_call.tool_name)

{drydock_cli-2.6.70 → drydock_cli-2.6.74}/drydock/core/prompts/gemma4.md

@@ -2,7 +2,13 @@ You are DryDock, a CLI coding agent. You write code, fix bugs, and build project
 
 ACT IMMEDIATELY. Your FIRST response must be a tool call — not text. Do NOT explain, plan, or ask. Call a tool NOW.
 
-Your tools: read_file, write_file, search_replace, grep, glob, bash, task.
+Your tools: read_file, write_file, search_replace, grep, glob, bash, task, web_search, web_fetch.
+
+WHEN TO USE WEB TOOLS (use sparingly, NOT for every task):
+- Stuck on an error you've tried to fix 2+ times without progress: `web_search` for the exact error message
+- Need an API example you don't remember (e.g. "how do I parse TOML with stdlib?"): `web_search`
+- Found a URL to a relevant SO post or doc page: `web_fetch` to read it
+- DO NOT web-search for things you already know how to do. Write the code first.
 
 DELEGATION (only for genuinely large tasks)
 

{drydock_cli-2.6.70 → drydock_cli-2.6.74}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "drydock-cli"
-version = "2.6.70"
+version = "2.6.74"
 description = "Local-first CLI coding agent — tested with Gemma 4 26B via vLLM"
 readme = "README.md"
 requires-python = ">=3.12"

drydock_cli-2.6.74/scripts/meta_ralph_loop.py

@@ -0,0 +1,376 @@
+#!/usr/bin/env python3
+"""Meta-RALPH loop — escalating sample+retry with stuck detection.
+
+Wraps ralph_loop's iteration logic with three escalation stages:
+
+  Stage 1  Standard iteration (one sample per fix prompt).
+  Stage 2  Best-of-3 sampling when progress stalls. Each sample runs
+           from a clean snapshot of the last good state; fastest winner
+           wins (first sample that improves tests is kept, others
+           discarded).
+  Stage 3  Stuck mode: inject a system note telling the TUI to:
+           - web_search the specific error
+           - consult worked_examples/ for the relevant pattern
+           - try a fundamentally different approach, not another rewrite
+
+Key difference from ralph_loop: when a fix iteration doesn't improve
+tests, we don't just roll back — we respawn the drydock TUI fresh and
+try again. Each new session re-reads the PRD and functional_tests from
+scratch, getting a different response trajectory (the model is
+stochastic enough that a fresh session produces different code).
+
+Usage:
+    python3 scripts/meta_ralph_loop.py \\
+        --cwd /data3/drydock_test_projects/406_mini_db \\
+        --pkg mini_db \\
+        --max-stages 3 \\
+        --samples-per-stage 3
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import pexpect
+
+DRYDOCK_BIN = "/home/bobef/miniforge3/envs/drydock/bin/drydock"
+SESSION_ROOT = Path.home() / ".vibe" / "logs" / "session"
+WORKED_EXAMPLES_DIR = Path("/data3/drydock/worked_examples")
+
+
+# ── Reuse the SessionWatcher and helpers from ralph_loop ──
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from ralph_loop import (  # type: ignore
+    SessionWatcher, type_prompt, drain_pty,
+    wait_for_prompt_landing, wait_for_completion,
+    run_functional_tests, snapshot_package, restore_snapshot,
+)
+
+
+def find_worked_example(cwd: Path, pkg: str, failure_output: str) -> tuple[str, str] | None:
+    """Find the best-matching worked example for the current task.
+
+    Returns (file_path, summary) or None. Keyword-matches against the
+    PRD text + last failure output.
+    """
+    lookup = WORKED_EXAMPLES_DIR / "lookup.json"
+    if not lookup.exists():
+        return None
+    try:
+        data = json.loads(lookup.read_text())
+    except Exception:
+        return None
+
+    # Collect search corpus: PRD + failure output + package name
+    corpus_parts = [pkg]
+    for fn in ("PRD.md", "PRD.master.md"):
+        p = cwd / fn
+        if p.exists():
+            corpus_parts.append(p.read_text(errors="ignore"))
+    if failure_output:
+        corpus_parts.append(failure_output)
+    corpus = " ".join(corpus_parts).lower()
+
+    best = None
+    best_score = 0
+    for entry in data.get("examples", []):
+        score = sum(1 for kw in entry.get("keywords", [])
+                    if kw.lower() in corpus)
+        if score > best_score:
+            best = entry
+            best_score = score
+
+    if not best or best_score < 2:
+        return None
+
+    fp = WORKED_EXAMPLES_DIR / best["file"]
+    if not fp.exists():
+        return None
+    return str(fp), best.get("summary", "")
+
+
+def spawn_drydock(cwd: Path, log_path: Path) -> pexpect.spawn:
+    env = {**os.environ, "TERM": "xterm-256color", "COLUMNS": "120", "LINES": "30"}
+    child = pexpect.spawn(DRYDOCK_BIN, encoding="utf-8", timeout=5,
+                          maxread=100000, env=env, cwd=str(cwd))
+    child.logfile_read = open(log_path, "w")
+    try:
+        child.expect([r">", r"Drydock", r"┌"], timeout=30)
+    except Exception:
+        pass
+    time.sleep(3)
+    try:
+        if "Trust this folder" in (child.before or ""):
+            child.send("\x1b[D")
+            time.sleep(0.2)
+            child.send("\r")
+            time.sleep(2)
+    except Exception:
+        pass
+    return child
+
+
+def terminate_drydock(child: pexpect.spawn) -> None:
+    try:
+        child.sendcontrol("c")
+        time.sleep(0.5)
+        child.terminate(force=True)
+    except Exception:
+        pass
+
+
+def run_single_session(cwd: Path, pkg: str, prompt: str,
+                       max_wait: int = 1200,
+                       idle_threshold: int = 180) -> tuple[int, int, str]:
+    """Spawn drydock, send ONE prompt, wait for it to finish,
+    return (test_pass, test_fail, output_tail)."""
+    log_path = Path(f"/tmp/meta_ralph_{pkg}_{int(time.time())}.log")
+    start_time = time.time()
+    child = spawn_drydock(cwd, log_path)
+    watcher = SessionWatcher(cwd, since=start_time)
+
+    try:
+        type_prompt(child, prompt)
+
+        # Wait for session to appear
+        for i in range(300):
+            drain_pty(child, 1.0)
+            if watcher.find_session():
+                break
+            if i > 0 and i % 60 == 0:
+                time.sleep(2)
+                type_prompt(child, prompt)
+        if not watcher.find_session():
+            return 0, 999, "session never appeared"
+
+        # Wait for prompt to land
+        if not wait_for_prompt_landing(child, watcher, 0, timeout=90):
+            time.sleep(5)
+            type_prompt(child, prompt)
+            if not wait_for_prompt_landing(child, watcher, 0, timeout=90):
+                return 0, 999, "prompt did not land"
+
+        # Wait for drydock to finish responding
+        wait_for_completion(child, watcher, max_wait=max_wait,
+                           idle_threshold=idle_threshold)
+    finally:
+        terminate_drydock(child)
+
+    p, f, out = run_functional_tests(cwd)
+    return p, f, out
+
+
+def best_of_n(cwd: Path, pkg: str, base_prompt: str, n: int,
+              current_best_pass: int, current_best_fail: int,
+              current_best_out: str,
+              snap: Path) -> tuple[int, int, str, Path]:
+    """Try the prompt N times, keeping the best result.
+
+    Between samples, restore the package from `snap`. If any sample
+    strictly improves test_pass count, return immediately (fastest win).
+
+    Returns (best_pass, best_fail, best_output, best_snap). If no sample
+    improves, returns the input values unchanged (callers can still
+    distinguish 'no progress' from 'all tests pass').
+    """
+    for i in range(n):
+        print(f"    [sample {i+1}/{n}]")
+        # Restore package from snapshot so each sample starts clean
+        restore_snapshot(cwd, pkg, snap)
+
+        p, f, out = run_single_session(cwd, pkg, base_prompt,
+                                        max_wait=1200,
+                                        idle_threshold=180)
+        print(f"      → {p}/{p+f} tests pass")
+
+        if p > current_best_pass:
+            # Win! Snapshot this state and return immediately.
+            new_snap = snapshot_package(cwd, pkg)
+            print(f"      [new best: {p}, keeping]")
+            return p, f, out, new_snap
+
+    # No sample beat current best — restore snap and return UNCHANGED
+    restore_snapshot(cwd, pkg, snap)
+    return current_best_pass, current_best_fail, current_best_out, snap
+
+
+def make_stuck_prompt(pkg: str, cwd: Path, failure_output: str) -> str:
+    """Build the stage-3 'stuck' prompt with web_search + worked-example hints."""
+    # Extract FAIL lines
+    fail_lines = [ln for ln in (failure_output or "").split("\n")
+                  if ln.startswith("FAIL:")][:5]
+    fail_text = "\n".join(fail_lines)
+
+    # Look up a worked example
+    example_path = None
+    example_summary = ""
+    matched = find_worked_example(cwd, pkg, failure_output)
+    if matched:
+        example_path, example_summary = matched
+
+    prompt = (
+        f"You've tried fixing the failures multiple times without progress. "
+        f"Current failures:\n\n{fail_text}\n\n"
+        f"DO SOMETHING DIFFERENT. Ideas:\n"
+        f"- Use `web_search` to look up the exact error message or the "
+        f"technique you're trying (e.g. 'python sql tokenizer example').\n"
+        f"- Use `web_fetch` to read a Stack Overflow answer or docs page.\n"
+        f"- Read a DIFFERENT source file than the one you've been rewriting — "
+        f"the bug may be upstream.\n"
+    )
+    if example_path:
+        prompt += (
+            f"\nA WORKED EXAMPLE is available at {example_path}\n"
+            f"Summary: {example_summary}\n"
+            f"Read it with read_file and use the STRUCTURE (not the exact "
+            f"code) to guide your fix.\n"
+        )
+    prompt += (
+        f"\nThen apply ONE targeted search_replace to fix ONE failure at a "
+        f"time. Do NOT rewrite whole files. Do NOT ask me for confirmation."
+    )
+    return prompt
+
+
+def meta_ralph(cwd: Path, pkg: str, max_stages: int = 3,
+               samples_per_stage: int = 3) -> dict:
+    """Main meta-RALPH loop."""
+    print(f"\n{'='*60}")
+    print(f"  META-RALPH: {pkg}")
+    print(f"  cwd: {cwd}")
+    print(f"  max stages: {max_stages}, samples/stage: {samples_per_stage}")
+    print(f"{'='*60}\n")
+
+    # Restore PRD.md
+    master = cwd / "PRD.master.md"
+    if master.exists():
+        shutil.copy2(master, cwd / "PRD.md")
+
+    start_time = time.time()
+    stages_log = []
+
+    # ── STAGE 1: Initial build (single sample, standard prompt) ──
+    print(f"─── STAGE 1: Initial build ───")
+    pkg_init = cwd / pkg / "__init__.py"
+    if pkg_init.exists():
+        initial_prompt = (
+            f"Look at the existing {pkg}/ directory and functional_tests.sh. "
+            f"Fix any failing tests with targeted search_replace patches."
+        )
+    else:
+        initial_prompt = (
+            f"Read PRD.md AND functional_tests.sh. Build the {pkg} package. "
+            f"Your CLI must conform to functional_tests.sh exactly. "
+            f"Create ALL files from the PRD. Write __init__.py, cli.py, "
+            f"__main__.py FIRST."
+        )
+
+    p, f, out = run_single_session(cwd, pkg, initial_prompt,
+                                    max_wait=1500, idle_threshold=180)
+    print(f"  Stage 1 result: {p}/{p+f} tests pass")
+    best_pass = p
+    best_fail = f
+    best_out = out
+    best_snap = snapshot_package(cwd, pkg)
+    stages_log.append({"stage": 1, "pass": p, "fail": f, "strategy": "single_build"})
+
+    # Early exit if perfect
+    if best_fail == 0 and best_pass > 0:
+        print(f"\n  ✓ All tests pass! Done at stage 1.")
+        return _report(cwd, pkg, start_time, stages_log, best_pass, best_fail)
+
+    # ── STAGE 2: best-of-N sampling ──
+    if max_stages >= 2:
+        print(f"\n─── STAGE 2: best-of-{samples_per_stage} sampling ───")
+        fail_lines = "\n".join(ln for ln in out.split("\n")
+                                if ln.startswith("FAIL:"))[:1500]
+        fix_prompt = (
+            f"Tests are failing:\n{fail_lines}\n\n"
+            f"Make TARGETED search_replace patches. Do not rewrite working files. "
+            f"Do not break currently-passing tests. Run bash functional_tests.sh "
+            f"when you think you're done."
+        )
+        p, f, out, best_snap = best_of_n(
+            cwd, pkg, fix_prompt, samples_per_stage,
+            best_pass, best_fail, best_out, best_snap,
+        )
+        print(f"  Stage 2 result: {p}/{p+f} tests pass")
+        best_pass, best_fail, best_out = p, f, out
+        stages_log.append({
+            "stage": 2, "pass": p, "fail": f,
+            "strategy": f"best_of_{samples_per_stage}",
+        })
+        if best_fail == 0 and best_pass > 0:
+            print(f"\n  ✓ All tests pass! Done at stage 2.")
+            return _report(cwd, pkg, start_time, stages_log, best_pass, best_fail)
+
+    # ── STAGE 3: stuck mode with web_search + worked example ──
+    if max_stages >= 3:
+        print(f"\n─── STAGE 3: stuck mode (web_search + worked example) ───")
+        stuck_prompt = make_stuck_prompt(pkg, cwd, best_out)
+        # One sample at a time; don't rollback — the stuck mode is a
+        # last-ditch effort, any improvement is worth keeping.
+        p, f, out = run_single_session(cwd, pkg, stuck_prompt,
+                                        max_wait=1800, idle_threshold=240)
+        print(f"  Stage 3 result: {p}/{p+f} tests pass")
+        if p > best_pass:
+            best_pass, best_fail, best_out = p, f, out
+            best_snap = snapshot_package(cwd, pkg)
+        else:
+            restore_snapshot(cwd, pkg, best_snap)
+        stages_log.append({
+            "stage": 3, "pass": p, "fail": f, "strategy": "stuck_mode",
+        })
+
+    return _report(cwd, pkg, start_time, stages_log, best_pass, best_fail)
+
+
+def _report(cwd: Path, pkg: str, start_time: float, stages_log: list,
+            best_pass: int, best_fail: int) -> dict:
+    total = int(time.time() - start_time)
+    print(f"\n{'='*60}")
+    print(f"  META-RALPH RESULTS: {pkg}")
+    print(f"  Total time: {total}s ({total/60:.1f}m)")
+    for s in stages_log:
+        print(f"  stage {s['stage']}: {s['pass']}/{s['pass']+s['fail']} "
+              f"({s['strategy']})")
+    print(f"\n  FINAL: {best_pass}/{best_pass+best_fail} tests pass")
+    print(f"{'='*60}\n")
+
+    report = {
+        "pkg": pkg,
+        "total_seconds": total,
+        "stages": stages_log,
+        "final_pass": best_pass,
+        "final_fail": best_fail,
+    }
+    out_path = Path(f"/tmp/meta_ralph_{pkg}_results.json")
+    with open(out_path, "w") as f:
+        json.dump(report, f, indent=2)
+    print(f"  Report: {out_path}")
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--cwd", required=True)
+    parser.add_argument("--pkg", required=True)
+    parser.add_argument("--max-stages", type=int, default=3)
+    parser.add_argument("--samples-per-stage", type=int, default=3)
+    args = parser.parse_args()
+    report = meta_ralph(
+        Path(args.cwd).resolve(), args.pkg,
+        args.max_stages, args.samples_per_stage,
+    )
+    return 0 if report["final_fail"] == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())