drydock-cli 0.6.3__tar.gz → 0.6.5__tar.gz

{drydock_cli-0.6.3 → drydock_cli-0.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 0.6.3
+Version: 0.6.5
 Summary: Drydock — nautical CLI coding agent
 Project-URL: Homepage, https://github.com/fbobe321/drydock
 Project-URL: Repository, https://github.com/fbobe321/drydock

drydock_cli-0.6.5/PRD.md

@@ -0,0 +1,180 @@
+# DryDock — Local CLI Coding Agent
+
+**Repository:** https://github.com/fbobe321/drydock
+**PyPI:** https://pypi.org/project/drydock-cli/ (v0.6.3)
+**License:** Apache 2.0 (fork of [mistralai/mistral-vibe](https://github.com/mistralai/mistral-vibe))
+**Status:** Active development — continuous improvement running
+
+---
+
+## Deployment Process
+
+Every change follows this pipeline:
+
+1. **Code** → modify files in `drydock/` package directory
+2. **Syntax check** → `python3 -c "import ast; ast.parse(...)"`
+3. **Regression tests** → 81 tests must pass (auto-run by deploy scripts)
+4. **Commit** → descriptive message with Co-Authored-By
+5. **Publish** → `./scripts/publish_to_pypi.sh` (tests → build → PyPI → GitHub)
+
+Scripts:
+- `scripts/deploy_to_github.sh` — runs tests, syncs to GitHub. Cron daily at 4 AM.
+- `scripts/publish_to_pypi.sh` — runs tests, bumps version, builds wheel, uploads to PyPI, deploys to GitHub. Aborts on test failure.
+
+Both scripts gate on the full 81-test regression suite. No deploy happens if tests fail.
+
+---
+
+## Regression Test Suite (81 tests)
+
+Two test files, run in 0.3s:
+
+```bash
+pytest tests/test_drydock_regression.py tests/test_drydock_tasks.py -p no:xdist -p no:cov --override-ini="addopts="
+```
+
+**test_drydock_regression.py (37 tests):**
+Message ordering (6), system note injection (3), wave spinner (2), config paths (3), state terms (4), Easter eggs (2), bash allowlist (5), conda detection (2), CLI flags (2), loop thresholds (1), write file safety (3), loop patterns (2), loading widget (2)
+
+**test_drydock_tasks.py (44 tests):**
+Binary file guard (5), unknown tool handling (1), loop thresholds (3), file I/O timeouts (4), skill discovery (3), config migration (2), system prompt content (3), bash allowlist (2), wave spinner (3), Easter eggs (1), injection guard (4), state file (4), context warnings (3), deviation rules (1), circuit breaker (2), CLI flags (2), thinking throttle (1)
+
+---
+
+## Continuous Improvement
+
+DryDock improves itself automatically and survives restarts:
+
+1. **`continuous_bench.sh`** runs SWE-bench batches in a loop (20 tasks, 600s timeout)
+2. **`@reboot` cron** restarts 2 minutes after any system restart
+3. **Every 6 hours** cron re-launches if the loop died
+4. **Daily at 4 AM** deploys to GitHub (with test gate)
+5. **State persists** in `continuous_bench_state.json`
+
+**Latest results (Mar 25):**
+- 520 task runs completed, 500/500 unique tasks covered
+- **254/500 passed (50.8%)** — up from 207/500 baseline (41.4%)
+- **+47 net improvement** (117 newly passing, 70 regressions from model non-determinism)
+
+---
+
+## Objective
+
+| | Value |
+|---|---|
+| **Baseline (Mar 15)** | 207/500 (41.4%) |
+| **Current (Mar 25)** | 254/500 (50.8%) |
+| **Net improvement** | +47 tasks (+9.4%) |
+| **Target** | 80%+ |
+| **Hardware** | 2x RTX 4060 Ti 16GB, devstral-24B-AWQ-4bit via vLLM, 128k context |
+
+---
+
+## Development Progress
+
+### Phase 1: Baseline & Analysis (Mar 14–20)
+1,138 task runs across 254 unique SWE-bench Verified tasks. Identified top failure modes: message ordering crashes (9%), wrong file edits (15%), loop kills (28%), prose-only responses (11%).
+
+### Phase 2: Core Agent Improvements (Mar 15–20)
+10 features: failure recovery middleware, fuzzy search_replace, grep source-first sorting, smarter loop detection, diagnostic/planner subagents, "never edit tests" rule, SWE-bench workflow prompt, .codeignore, message ordering fix.
+
+### Phase 3: Crash Elimination (Mar 23)
+`_sanitize_message_ordering()` safety net, middleware safe injection, MessageList bug fix, loop threshold tuning, forced-edit nudges, ConversationLimitException exit 0. Result: zero crashes.
+
+### Phase 4: Conda/Pip & Rebrand (Mar 23)
+Bash tool allowlist (pip, conda, pytest auto-approve), conda environment detection via BASH_ENV, full Mistral Vibe → DryDock rebrand. Published to GitHub.
+
+### Phase 5: UX Overhaul (Mar 24)
+Wave spinner, .drydock config dir, double Ctrl-C, --dangerously-skip-permissions, nautical Easter eggs, status throttle, write file timeouts, binary file guard, pptx skill, bash abuse detection, alternating loop detection, progressive budget warnings, ambiguous prompt guard, message queuing, mouse scroll, ocean blue onboarding. 76 regression tests gating deploys.
+
+### Phase 5b: Package Rename (Mar 24)
+`vibe/` → `drydock/` directory rename (908 imports, 257 files). Published to PyPI as drydock-cli. Removed `vibe` CLI entry point.
+
+### Phase 6: GSD Integration & Performance (Mar 25)
+
+Inspired by [get-shit-done](https://github.com/gsd-build/get-shit-done) (41k stars):
+
+| Feature | Details |
+|---------|---------|
+| Tiered context warnings | 4 levels at 50/65/75/85% usage, debounced every 5 calls |
+| Prompt injection guard | Detects role overrides, invisible Unicode, hidden instructions |
+| Structured state file | `.drydock/state.md` persists task context across sessions |
+| Deviation handling rules | Auto-fix bugs/imports, ask user for architecture/scope decisions |
+| Circuit breaker | Blocks exact same tool call after 2 attempts with "already attempted" summary |
+| Thinking flicker fix | Status words change every 4s, not every token |
+| Conda env protection | Preserves user's active environment in subprocesses |
+| `--insecure` / `-k` flag | Disables SSL verification for corporate proxies |
+| `/consult` command | Ask a smarter model for advice — response visible to local model |
+| `consultant_model` config | Select consultant from configured models in config.toml |
+| `.vibe` auto-migration | Copies ~/.vibe → ~/.drydock on first run |
+
+---
+
+## Architecture
+
+```
+drydock/
+├── PRD.md                                  ← This document
+├── NOTICE                                  ← Apache 2.0 attribution
+├── drydock/
+│   ├── core/
+│   │   ├── agent_loop.py                   ← Loop detection, circuit breaker, message ordering
+│   │   ├── consultant.py                   ← /consult command backend (read-only advisor)
+│   │   ├── middleware.py                   ← Tiered context warnings
+│   │   ├── programmatic.py                 ← Headless API entry point
+│   │   ├── session/state_file.py           ← Cross-session state persistence
+│   │   ├── tools/injection_guard.py        ← Prompt injection detection
+│   │   ├── tools/builtins/bash.py          ← Shell, conda/pip, allowlist/denylist
+│   │   ├── tools/builtins/search_replace.py ← Fuzzy auto-apply, recovery hints
+│   │   └── prompts/cli.md                  ← System prompt with deviation rules
+│   ├── cli/
+│   │   ├── entrypoint.py                   ← CLI flags (--insecure, --consultant, etc.)
+│   │   ├── commands.py                     ← Slash commands (/consult, /help, etc.)
+│   │   └── textual_ui/app.py              ← TUI, message queuing, double Ctrl-C
+│   └── skills/
+│       └── create-presentation/SKILL.md    ← Bundled pptx skill
+├── tests/
+│   ├── test_drydock_regression.py          ← 37 component tests
+│   └── test_drydock_tasks.py               ← 44 behavior tests
+└── scripts/
+    ├── deploy_to_github.sh                 ← Test-gated GitHub deploy
+    └── publish_to_pypi.sh                  ← Test-gated PyPI publish
+```
+
+---
+
+## Key Technical Decisions
+
+**Circuit breaker:** Tracks tool call signatures (hash of name + args). After 2 identical calls, blocks execution and returns the cached result with "ALREADY ATTEMPTED" summary and suggestions to try different approaches.
+
+**Consultant model:** `/consult` sends a question to a configured model using DryDock's own backend (same providers, same API keys). The consultant never calls tools — it only returns text advice that gets injected into the conversation so the local model can see and act on it.
+
+**Tiered context warnings:** 4 warning levels (50%, 65%, 75%, 85% context used). Debounced every 5 tool calls. Messages escalate from "wrap up" to "STOP NOW."
+
+**Config migration:** On first run, if `~/.vibe` exists but `~/.drydock` doesn't, auto-copies everything and leaves a `MIGRATED.txt` note.
+
+---
+
+## Lessons Learned
+
+1. **Fix bugs before adding features.** The message ordering crash fix was worth more than all subagents combined.
+2. **Non-determinism is real.** Run 500+ tasks to get stable numbers. 20-task batches are noise.
+3. **The model needs hard guardrails, not suggestions.** The circuit breaker (block after 2) works better than warnings (which the model ignores).
+4. **Test everything.** 81 regression tests catch issues before they ship. Gate deploys on tests.
+5. **Users find different bugs than benchmarks.** SWE-bench found crash bugs. Real usage found UX bugs (flicker, loops, wrong config dirs).
+
+---
+
+## Next Steps
+
+### P1: Startup optimization
+20-second delay on launch. Profile imports, lazy-load heavy modules.
+
+### P2: Expand to full SWE-bench (2,294 tasks)
+Batch file ready. Switch continuous_bench.sh once Verified is stable.
+
+### P3: Task queue UI
+Show the user what the agent has planned in its execution pipeline.
+
+### P4: Support more LLM backends
+Test with Claude, GPT-4, Gemini to understand which improvements are model-specific.

{drydock_cli-0.6.3 → drydock_cli-0.6.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "drydock-cli"
-version = "0.6.3"
+version = "0.6.5"
 description = "Drydock — nautical CLI coding agent"
 readme = "README.md"
 requires-python = ">=3.12"

{drydock_cli-0.6.3 → drydock_cli-0.6.5}/scripts/deploy_to_github.sh

@@ -37,7 +37,7 @@ AUTH_URL="https://${GITHUB_TOKEN}@github.com/fbobe321/drydock.git"
 
 log "Running regression tests..."
 cd "$DRYDOCK_SRC"
-if ! python3 -m pytest tests/test_drydock_regression.py tests/test_drydock_tasks.py \
+if ! python3 -m pytest tests/test_drydock_regression.py tests/test_drydock_tasks.py tests/test_loop_detection.py \
     -p no:xdist -p no:cov --override-ini="addopts=" -q 2>&1; then
     log "TESTS FAILED — deploy aborted. Fix the tests before deploying."
     exit 1

{drydock_cli-0.6.3 → drydock_cli-0.6.5}/scripts/publish_to_pypi.sh

@@ -25,7 +25,7 @@ PYPI_TOKEN=$(cat "$TOKEN_FILE")
 
 # --- Run tests ---
 log "Running regression tests..."
-if ! $PYTHON -m pytest tests/test_drydock_regression.py tests/test_drydock_tasks.py \
+if ! $PYTHON -m pytest tests/test_drydock_regression.py tests/test_drydock_tasks.py tests/test_loop_detection.py \
     -p no:xdist -p no:cov --override-ini="addopts=" -q 2>&1; then
     log "TESTS FAILED — publish aborted."
     exit 1

drydock_cli-0.6.5/tests/test_loop_detection.py

@@ -0,0 +1,398 @@
+"""Comprehensive loop detection tests.
+
+Simulates real message histories that trigger each loop detection mechanism.
+These test the exact scenarios users report:
+- Running `ls -ltr` 5+ times (circuit breaker)
+- Exact same grep repeated 8+ times (Check 1: REPEAT_WARNING)
+- 10 consecutive bash calls with different args (Check 2: same-tool)
+- Reading the same file 5+ times with different offsets (Check 3: same-file)
+- Alternating grep→read_file→grep→read_file (Check 4: alternating)
+- Bash abuse: 10+ bash calls without making an edit
+"""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from drydock.core.agent_loop import (
+    AgentLoop,
+    MAX_TOOL_TURNS,
+    REPEAT_FORCE_STOP_THRESHOLD,
+    REPEAT_WARNING_THRESHOLD,
+)
+from drydock.core.types import LLMMessage, MessageList, Role, ToolCall, FunctionCall
+
+
+def _make_agent() -> AgentLoop:
+    """Create a minimal AgentLoop for testing loop detection."""
+    al = object.__new__(AgentLoop)
+    al.messages = MessageList()
+    al._tool_call_history = {}
+    return al
+
+
+def _add_tool_call(al: AgentLoop, tool_name: str, arguments: str = "{}") -> None:
+    """Add an assistant message with a tool call + a tool result."""
+    al.messages.append(LLMMessage(
+        role=Role.assistant,
+        content="",
+        tool_calls=[ToolCall(
+            id=f"call_{len(al.messages)}",
+            function=FunctionCall(name=tool_name, arguments=arguments),
+        )],
+    ))
+    al.messages.append(LLMMessage(
+        role=Role.tool,
+        content=f"Result of {tool_name}",
+    ))
+
+
+# ============================================================================
+# Circuit Breaker Tests
+# ============================================================================
+
+class TestCircuitBreaker:
+    """The circuit breaker blocks the EXACT same tool call after 2 attempts."""
+
+    def test_first_call_allowed(self):
+        al = _make_agent()
+        tc = SimpleNamespace(tool_name="bash", raw_arguments='{"command":"ls -ltr"}')
+        assert al._circuit_breaker_check(tc) is None
+
+    def test_second_call_allowed(self):
+        al = _make_agent()
+        tc = SimpleNamespace(tool_name="bash", raw_arguments='{"command":"ls -ltr"}')
+        al._circuit_breaker_record(tc, "file1.py\nfile2.py")
+        assert al._circuit_breaker_check(tc) is None
+
+    def test_third_call_blocked(self):
+        al = _make_agent()
+        tc = SimpleNamespace(tool_name="bash", raw_arguments='{"command":"ls -ltr"}')
+        al._circuit_breaker_record(tc, "file1.py\nfile2.py")
+        al._circuit_breaker_record(tc, "file1.py\nfile2.py")
+        result = al._circuit_breaker_check(tc)
+        assert result is not None
+        assert "CIRCUIT BREAKER" in result
+
+    def test_blocked_message_contains_previous_result(self):
+        al = _make_agent()
+        tc = SimpleNamespace(tool_name="bash", raw_arguments='{"command":"ls -ltr"}')
+        al._circuit_breaker_record(tc, "important_file.py")
+        al._circuit_breaker_record(tc, "important_file.py")
+        result = al._circuit_breaker_check(tc)
+        assert "important_file.py" in result
+
+    def test_blocked_message_contains_alternatives(self):
+        al = _make_agent()
+        tc = SimpleNamespace(tool_name="bash", raw_arguments='{"command":"ls -ltr"}')
+        al._circuit_breaker_record(tc, "output")
+        al._circuit_breaker_record(tc, "output")
+        result = al._circuit_breaker_check(tc)
+        assert "DIFFERENT" in result or "different" in result
+
+    def test_different_args_not_blocked(self):
+        al = _make_agent()
+        tc1 = SimpleNamespace(tool_name="bash", raw_arguments='{"command":"ls -ltr"}')
+        tc2 = SimpleNamespace(tool_name="bash", raw_arguments='{"command":"ls -la"}')
+        al._circuit_breaker_record(tc1, "r1")
+        al._circuit_breaker_record(tc1, "r1")
+        assert al._circuit_breaker_check(tc1) is not None  # Blocked
+        assert al._circuit_breaker_check(tc2) is None       # Not blocked
+
+    def test_different_tools_not_blocked(self):
+        al = _make_agent()
+        tc1 = SimpleNamespace(tool_name="bash", raw_arguments='{"command":"ls"}')
+        tc2 = SimpleNamespace(tool_name="grep", raw_arguments='{"pattern":"foo"}')
+        al._circuit_breaker_record(tc1, "r1")
+        al._circuit_breaker_record(tc1, "r1")
+        assert al._circuit_breaker_check(tc1) is not None
+        assert al._circuit_breaker_check(tc2) is None
+
+    def test_already_attempted_summary(self):
+        al = _make_agent()
+        tc = SimpleNamespace(tool_name="bash", raw_arguments='{"command":"ls"}')
+        al._circuit_breaker_record(tc, "output1")
+        al._circuit_breaker_record(tc, "output1")
+        result = al._circuit_breaker_check(tc)
+        assert "ALREADY ATTEMPTED" in result
+
+
+# ============================================================================
+# Check 1: Exact Same Tool Call Repeated (REPEAT_WARNING_THRESHOLD)
+# ============================================================================
+
+class TestExactRepeatDetection:
+    """Detects the same tool call (name + args) repeated N+ times."""
+
+    def test_no_repeats_returns_none(self):
+        al = _make_agent()
+        _add_tool_call(al, "bash", '{"command":"ls"}')
+        _add_tool_call(al, "grep", '{"pattern":"foo"}')
+        _add_tool_call(al, "read_file", '{"path":"x.py"}')
+        assert al._check_tool_call_repetition() is None
+
+    def test_warning_at_threshold(self):
+        al = _make_agent()
+        args = '{"command":"ls -ltr"}'
+        for _ in range(REPEAT_WARNING_THRESHOLD):
+            _add_tool_call(al, "bash", args)
+        result = al._check_tool_call_repetition()
+        assert result is not None
+        assert "WARNING" in result
+
+    def test_below_threshold_returns_none(self):
+        al = _make_agent()
+        args = '{"command":"ls -ltr"}'
+        for _ in range(REPEAT_WARNING_THRESHOLD - 1):
+            _add_tool_call(al, "bash", args)
+        assert al._check_tool_call_repetition() is None
+
+    def test_force_stop_at_threshold(self):
+        """25 exact repeats. Check 2 (same-tool at 8) catches it first as WARNING."""
+        al = _make_agent()
+        args = '{"command":"ls -ltr"}'
+        for _ in range(REPEAT_FORCE_STOP_THRESHOLD):
+            _add_tool_call(al, "bash", args)
+        result = al._check_tool_call_repetition()
+        # Same-tool consecutive check (8 for bash) fires before exact-repeat (25)
+        assert result is not None
+        assert "WARNING" in result or result == "FORCE_STOP"
+
+    def test_mixed_calls_dont_trigger(self):
+        al = _make_agent()
+        for i in range(20):
+            _add_tool_call(al, "bash", json.dumps({"command": f"cmd_{i}"}))
+        # All different args — shouldn't trigger exact repeat
+        result = al._check_tool_call_repetition()
+        # Might trigger same-tool check but not exact repeat
+        if result:
+            assert "FORCE_STOP" not in result
+
+
+# ============================================================================
+# Check 2: Same Tool Consecutive (Different Args)
+# ============================================================================
+
+class TestSameToolConsecutive:
+    """Detects the same tool used N+ times in a row with different args."""
+
+    def test_8_consecutive_bash_triggers_warning(self):
+        al = _make_agent()
+        for i in range(8):
+            _add_tool_call(al, "bash", json.dumps({"command": f"cmd_{i}"}))
+        result = al._check_tool_call_repetition()
+        assert result is not None
+        assert "WARNING" in result
+        assert "bash" in result
+
+    def test_7_consecutive_bash_no_warning(self):
+        al = _make_agent()
+        for i in range(7):
+            _add_tool_call(al, "bash", json.dumps({"command": f"cmd_{i}"}))
+        result = al._check_tool_call_repetition()
+        assert result is None
+
+    def test_10_consecutive_grep_triggers_warning(self):
+        al = _make_agent()
+        for i in range(10):
+            _add_tool_call(al, "grep", json.dumps({"pattern": f"pattern_{i}"}))
+        result = al._check_tool_call_repetition()
+        assert result is not None
+        assert "WARNING" in result
+
+    def test_9_consecutive_grep_no_warning(self):
+        al = _make_agent()
+        for i in range(9):
+            _add_tool_call(al, "grep", json.dumps({"pattern": f"pattern_{i}"}))
+        assert al._check_tool_call_repetition() is None
+
+    def test_interleaved_tools_dont_trigger(self):
+        al = _make_agent()
+        for i in range(20):
+            tool = "bash" if i % 2 == 0 else "grep"
+            _add_tool_call(al, tool, json.dumps({"arg": f"val_{i}"}))
+        # Not consecutive same tool — shouldn't trigger Check 2
+        # (might trigger Check 4 alternating though)
+        result = al._check_tool_call_repetition()
+        # Just verify it doesn't crash
+        assert result is None or "WARNING" in result
+
+
+# ============================================================================
+# Check 3: Same File Read 5+ Times
+# ============================================================================
+
+class TestSameFileReadLoop:
+    """Detects reading the same file 5+ times (different offsets)."""
+
+    def test_5_reads_same_file_triggers(self):
+        al = _make_agent()
+        for i in range(5):
+            _add_tool_call(al, "read_file", json.dumps({
+                "path": "src/auth.py", "offset": i * 50, "limit": 50
+            }))
+        result = al._check_tool_call_repetition()
+        assert result is not None
+        assert "WARNING" in result
+
+    def test_4_reads_same_file_no_trigger(self):
+        al = _make_agent()
+        for i in range(4):
+            _add_tool_call(al, "read_file", json.dumps({
+                "path": "src/auth.py", "offset": i * 50
+            }))
+        # 4 reads shouldn't trigger (threshold is 5)
+        # But might trigger same-tool-consecutive if we hit that threshold
+        result = al._check_tool_call_repetition()
+        # At 4 reads, same-tool limit for read_file is 10, so no trigger
+        assert result is None
+
+    def test_5_reads_different_files_no_trigger(self):
+        al = _make_agent()
+        for i in range(5):
+            _add_tool_call(al, "read_file", json.dumps({
+                "path": f"src/file_{i}.py"
+            }))
+        result = al._check_tool_call_repetition()
+        assert result is None
+
+
+# ============================================================================
+# Check 4: Alternating Tool Pattern (A→B→A→B)
+# ============================================================================
+
+class TestAlternatingPattern:
+    """Detects A→B→A→B→A→B→A→B alternating patterns."""
+
+    def test_8_alternating_triggers(self):
+        al = _make_agent()
+        for i in range(8):
+            tool = "grep" if i % 2 == 0 else "read_file"
+            _add_tool_call(al, tool, json.dumps({"arg": f"val_{i}"}))
+        result = al._check_tool_call_repetition()
+        assert result is not None
+        assert "WARNING" in result
+
+    def test_6_alternating_no_trigger(self):
+        al = _make_agent()
+        for i in range(6):
+            tool = "grep" if i % 2 == 0 else "read_file"
+            _add_tool_call(al, tool, json.dumps({"arg": f"val_{i}"}))
+        result = al._check_tool_call_repetition()
+        assert result is None
+
+    def test_3_tool_cycle_no_trigger(self):
+        """A→B→C→A→B→C shouldn't trigger the 2-tool alternating check."""
+        al = _make_agent()
+        tools = ["grep", "read_file", "bash"]
+        for i in range(9):
+            _add_tool_call(al, tools[i % 3], json.dumps({"arg": f"val_{i}"}))
+        result = al._check_tool_call_repetition()
+        # 3-tool cycles are not detected by Check 4 (which only checks 2-tool)
+        # Might trigger same-tool-consecutive for individual tools though
+        assert result is None or "FORCE_STOP" not in result
+
+
+# ============================================================================
+# Threshold Constants
+# ============================================================================
+
+class TestThresholdConstants:
+    """Verify threshold constants are reasonable."""
+
+    def test_max_tool_turns_ceiling(self):
+        assert MAX_TOOL_TURNS <= 200
+        assert MAX_TOOL_TURNS >= 50
+
+    def test_warning_before_force_stop(self):
+        assert REPEAT_WARNING_THRESHOLD < REPEAT_FORCE_STOP_THRESHOLD
+
+    def test_warning_threshold_not_too_low(self):
+        assert REPEAT_WARNING_THRESHOLD >= 6
+
+    def test_force_stop_not_too_high(self):
+        assert REPEAT_FORCE_STOP_THRESHOLD <= 30
+
+
+# ============================================================================
+# Real-World Loop Scenarios
+# ============================================================================
+
+class TestRealWorldLoops:
+    """Simulate actual user-reported looping scenarios."""
+
+    def test_ls_ltr_loop(self):
+        """User reports: `ls -ltr` runs 5+ times."""
+        al = _make_agent()
+        tc = SimpleNamespace(tool_name="bash", raw_arguments='{"command":"ls -ltr"}')
+
+        # First 2 calls go through
+        al._circuit_breaker_record(tc, "total 48\n-rw-r--r-- 1 user user 1234 auth.py")
+        al._circuit_breaker_record(tc, "total 48\n-rw-r--r-- 1 user user 1234 auth.py")
+
+        # 3rd call is blocked
+        assert al._circuit_breaker_check(tc) is not None
+
+    def test_grep_same_pattern_loop(self):
+        """Model greps for the same pattern 10 times."""
+        al = _make_agent()
+        for _ in range(REPEAT_WARNING_THRESHOLD):
+            _add_tool_call(al, "grep", '{"pattern":"def authenticate","path":"."}')
+        assert al._check_tool_call_repetition() is not None
+
+    def test_read_file_offset_evasion(self):
+        """Model reads same file with incrementing offset to evade detection."""
+        al = _make_agent()
+        for i in range(5):
+            _add_tool_call(al, "read_file", json.dumps({
+                "path": "django/db/models/query.py",
+                "offset": i * 100,
+                "limit": 100,
+            }))
+        assert al._check_tool_call_repetition() is not None
+
+    def test_bash_exploration_loop(self):
+        """Model runs 8+ different bash commands exploring the filesystem."""
+        al = _make_agent()
+        commands = [
+            "find . -name '*.py'", "ls src/", "cat README.md",
+            "wc -l src/*.py", "head -20 setup.py", "ls -la tests/",
+            "find . -type f | wc -l", "du -sh src/",
+        ]
+        for cmd in commands:
+            _add_tool_call(al, "bash", json.dumps({"command": cmd}))
+        result = al._check_tool_call_repetition()
+        assert result is not None  # 8 consecutive bash calls
+
+    def test_grep_read_alternation(self):
+        """Model alternates between grep and read_file without making progress."""
+        al = _make_agent()
+        for i in range(8):
+            if i % 2 == 0:
+                _add_tool_call(al, "grep", json.dumps({"pattern": f"func_{i//2}"}))
+            else:
+                _add_tool_call(al, "read_file", json.dumps({"path": f"file_{i//2}.py"}))
+        assert al._check_tool_call_repetition() is not None
+
+    def test_normal_workflow_no_false_positive(self):
+        """A normal workflow: grep → read → edit → verify should NOT trigger."""
+        al = _make_agent()
+        _add_tool_call(al, "grep", '{"pattern":"def login"}')
+        _add_tool_call(al, "read_file", '{"path":"auth.py","offset":10,"limit":20}')
+        _add_tool_call(al, "search_replace", '{"file_path":"auth.py","content":"..."}')
+        _add_tool_call(al, "read_file", '{"path":"auth.py","offset":10,"limit":20}')
+        assert al._check_tool_call_repetition() is None
+
+    def test_investigate_then_fix_no_false_positive(self):
+        """3 greps + 2 reads + 1 edit = normal bug fix workflow."""
+        al = _make_agent()
+        _add_tool_call(al, "grep", '{"pattern":"class User"}')
+        _add_tool_call(al, "grep", '{"pattern":"def save"}')
+        _add_tool_call(al, "read_file", '{"path":"models.py"}')
+        _add_tool_call(al, "grep", '{"pattern":"validate"}')
+        _add_tool_call(al, "read_file", '{"path":"validators.py"}')
+        _add_tool_call(al, "search_replace", '{"file_path":"models.py","content":"..."}')
+        assert al._check_tool_call_repetition() is None