refactor: Phase 2b — consolidate 28 modules into 14 packages

Complete the module consolidation planned in REFACTORING_PLAN.md:

Modules merged:
- work_orders/ + task_queue/ → swarm/ (subpackages)
- self_modify/ + self_tdd/ + upgrades/ → self_coding/ (subpackages)
- tools/ → creative/tools/
- chat_bridge/ + telegram_bot/ + shortcuts/ + voice/ → integrations/ (new)
- ws_manager/ + notifications/ + events/ + router/ → infrastructure/ (new)
- agents/ + agent_core/ + memory/ → timmy/ (subpackages)

Updated across codebase:
- 66 source files: import statements rewritten
- 13 test files: import + patch() target strings rewritten
- pyproject.toml: wheel includes (28→14), entry points updated
- CLAUDE.md: singleton paths, module map, entry points table
- AGENTS.md: file convention updates
- REFACTORING_PLAN.md: execution status, success metrics

Extras:
- Module-level CLAUDE.md added to 6 key packages (Phase 6.2)
- Zero test regressions: 1462 tests passing

https://claude.ai/code/session_01JNjWfHqusjT3aiN4vvYgUk

src/self_coding/CLAUDE.md

@@ -0,0 +1,23 @@
+# self_coding/ — Module Guide
+
+Self-modification infrastructure with safety constraints.
+
+## Structure
+- `git_safety.py` — Atomic git operations with rollback
+- `codebase_indexer.py` — Live mental model of the codebase
+- `modification_journal.py` — Persistent log of modification attempts
+- `reflection.py` — Generate lessons learned
+- `self_modify/` — Runtime self-modification loop (LLM-driven)
+- `self_tdd/` — Continuous test watchdog
+- `upgrades/` — Self-upgrade approval queue
+
+## Entry points
+```toml
+self-tdd = "self_coding.self_tdd.watchdog:main"
+self-modify = "self_coding.self_modify.cli:main"
+```
+
+## Testing
+```bash
+pytest tests/self_coding/ -q
+```

src/self_coding/self_modify/__init__.py

@@ -0,0 +1 @@
+"""Self-Modify — Runtime self-modification with safety constraints."""

src/self_coding/self_modify/cli.py

@@ -0,0 +1,134 @@
+"""CLI for self-modification — run from the terminal.
+
+Usage:
+    self-modify run "Add a docstring to src/timmy/prompts.py" --file src/timmy/prompts.py
+    self-modify run "Fix the bug in config" --dry-run
+    self-modify run "Add logging" --backend anthropic --autonomous
+    self-modify status
+"""
+
+import logging
+import os
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+app = typer.Typer(help="Timmy self-modify — edit code, run tests, commit")
+
+
+@app.command()
+def run(
+    instruction: str = typer.Argument(..., help="What to change (natural language)"),
+    file: Optional[list[str]] = typer.Option(None, "--file", "-f", help="Target file(s) to modify"),
+    dry_run: bool = typer.Option(False, "--dry-run", "-n", help="Generate edits but don't write"),
+    retries: int = typer.Option(2, "--retries", "-r", help="Max retry attempts on test failure"),
+    backend: Optional[str] = typer.Option(None, "--backend", "-b", help="LLM backend: ollama, anthropic, auto"),
+    autonomous: bool = typer.Option(False, "--autonomous", "-a", help="Enable autonomous self-correction"),
+    max_cycles: int = typer.Option(3, "--max-cycles", help="Max autonomous correction cycles"),
+    branch: bool = typer.Option(False, "--branch", help="Create a git branch (off by default to avoid container restarts)"),
+    speak: bool = typer.Option(False, "--speak", "-s", help="Speak the result via TTS"),
+):
+    """Run the self-modification loop."""
+    # Force enable for CLI usage
+    os.environ["SELF_MODIFY_ENABLED"] = "true"
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)-8s %(name)s -- %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    # Skip branch creation unless explicitly requested
+    if not branch:
+        os.environ["SELF_MODIFY_SKIP_BRANCH"] = "1"
+
+    from self_coding.self_modify.loop import SelfModifyLoop, ModifyRequest
+
+    target_files = list(file) if file else []
+    effective_backend = backend or os.environ.get("SELF_MODIFY_BACKEND", "auto")
+
+    console.print(Panel(
+        f"[bold]Instruction:[/bold] {instruction}\n"
+        f"[bold]Files:[/bold] {', '.join(target_files) or '(auto-detect)'}\n"
+        f"[bold]Backend:[/bold] {effective_backend}\n"
+        f"[bold]Autonomous:[/bold] {autonomous}\n"
+        f"[bold]Dry run:[/bold] {dry_run}\n"
+        f"[bold]Max retries:[/bold] {retries}",
+        title="Self-Modify",
+        border_style="cyan",
+    ))
+
+    loop = SelfModifyLoop(
+        max_retries=retries,
+        backend=effective_backend,
+        autonomous=autonomous,
+        max_autonomous_cycles=max_cycles,
+    )
+    request = ModifyRequest(
+        instruction=instruction,
+        target_files=target_files,
+        dry_run=dry_run,
+    )
+
+    with console.status("[bold cyan]Running self-modification loop..."):
+        result = loop.run(request)
+
+    if result.report_path:
+        console.print(f"\n[dim]Report saved: {result.report_path}[/dim]\n")
+
+    if result.success:
+        console.print(Panel(
+            f"[green bold]SUCCESS[/green bold]\n\n"
+            f"Files changed: {', '.join(result.files_changed)}\n"
+            f"Tests passed: {result.test_passed}\n"
+            f"Commit: {result.commit_sha or 'none (dry run)'}\n"
+            f"Branch: {result.branch_name or 'current'}\n"
+            f"Attempts: {result.attempts}\n"
+            f"Autonomous cycles: {result.autonomous_cycles}",
+            title="Result",
+            border_style="green",
+        ))
+    else:
+        console.print(Panel(
+            f"[red bold]FAILED[/red bold]\n\n"
+            f"Error: {result.error}\n"
+            f"Attempts: {result.attempts}\n"
+            f"Autonomous cycles: {result.autonomous_cycles}",
+            title="Result",
+            border_style="red",
+        ))
+        raise typer.Exit(1)
+
+    if speak and result.success:
+        try:
+            from timmy_serve.voice_tts import voice_tts
+            if voice_tts.available:
+                voice_tts.speak_sync(
+                    f"Code modification complete. "
+                    f"{len(result.files_changed)} files changed. Tests passing."
+                )
+        except Exception:
+            pass
+
+
+@app.command()
+def status():
+    """Show whether self-modification is enabled."""
+    from config import settings
+    enabled = settings.self_modify_enabled
+    color = "green" if enabled else "red"
+    console.print(f"Self-modification: [{color}]{'ENABLED' if enabled else 'DISABLED'}[/{color}]")
+    console.print(f"Max retries: {settings.self_modify_max_retries}")
+    console.print(f"Backend: {settings.self_modify_backend}")
+    console.print(f"Allowed dirs: {settings.self_modify_allowed_dirs}")
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

src/self_coding/self_modify/loop.py

@@ -0,0 +1,741 @@
+"""Self-modification loop — read source, generate edits, test, commit.
+
+Orchestrates the full cycle for Timmy to modify its own codebase:
+1. Create a working git branch
+2. Read target source files
+3. Send instruction + source to the LLM
+4. Validate syntax before writing
+5. Write edits to disk
+6. Run pytest
+7. On success -> git add + commit; on failure -> revert
+8. On total failure -> diagnose from report, restart autonomously
+
+Supports multiple LLM backends:
+- "ollama"   — local Ollama (default, sovereign)
+- "anthropic" — Claude API via Anthropic SDK
+- "auto"     — try anthropic first (if key set), fall back to ollama
+
+Reports are saved to data/self_modify_reports/ for debugging.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import subprocess
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+# Project root — two levels up from src/self_modify/
+PROJECT_ROOT = Path(__file__).parent.parent.parent
+
+# Reports directory
+REPORTS_DIR = PROJECT_ROOT / "data" / "self_modify_reports"
+
+# Only one self-modification at a time
+_LOCK = threading.Lock()
+
+# Maximum file size we'll send to the LLM (bytes)
+_MAX_FILE_SIZE = 50_000
+
+# Delimiter format the LLM is instructed to use
+_FILE_BLOCK_RE = re.compile(
+    r"---\s*FILE:\s*(.+?)\s*---\n(.*?)---\s*END\s*FILE\s*---",
+    re.DOTALL,
+)
+
+# Backend type literal
+BACKENDS = ("ollama", "anthropic", "auto")
+
+
+@dataclass
+class ModifyRequest:
+    """A request to modify code."""
+
+    instruction: str
+    target_files: list[str] = field(default_factory=list)
+    dry_run: bool = False
+
+
+@dataclass
+class ModifyResult:
+    """Result of a self-modification attempt."""
+
+    success: bool
+    files_changed: list[str] = field(default_factory=list)
+    test_passed: bool = False
+    commit_sha: Optional[str] = None
+    branch_name: Optional[str] = None
+    error: Optional[str] = None
+    llm_response: str = ""
+    attempts: int = 0
+    report_path: Optional[str] = None
+    autonomous_cycles: int = 0
+
+
+class SelfModifyLoop:
+    """Orchestrates the read -> edit -> test -> commit cycle.
+
+    Supports autonomous self-correction: when all retries fail, reads its own
+    failure report, diagnoses the root cause, and restarts with a corrected
+    instruction.
+    """
+
+    def __init__(
+        self,
+        repo_path: Optional[Path] = None,
+        max_retries: Optional[int] = None,
+        backend: Optional[str] = None,
+        autonomous: bool = False,
+        max_autonomous_cycles: int = 3,
+    ) -> None:
+        self._repo_path = repo_path or PROJECT_ROOT
+        self._max_retries = (
+            max_retries if max_retries is not None else settings.self_modify_max_retries
+        )
+        self._allowed_dirs = [
+            d.strip() for d in settings.self_modify_allowed_dirs.split(",") if d.strip()
+        ]
+        self._run_id = f"{int(time.time())}"
+        self._attempt_reports: list[dict] = []
+        self._backend = backend or settings.self_modify_backend
+        self._autonomous = autonomous
+        self._max_autonomous_cycles = max_autonomous_cycles
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def run(self, request: ModifyRequest) -> ModifyResult:
+        """Execute the full self-modification loop."""
+        if not settings.self_modify_enabled:
+            return ModifyResult(
+                success=False,
+                error="Self-modification is disabled. Set SELF_MODIFY_ENABLED=true.",
+            )
+
+        if not _LOCK.acquire(blocking=False):
+            return ModifyResult(
+                success=False,
+                error="Another self-modification is already running.",
+            )
+
+        try:
+            result = self._run_locked(request)
+            report_path = self._save_report(request, result)
+            result.report_path = str(report_path)
+
+            # Autonomous mode: if failed, diagnose and restart
+            if self._autonomous and not result.success and not request.dry_run:
+                result = self._autonomous_loop(request, result, report_path)
+
+            return result
+        finally:
+            _LOCK.release()
+
+    # ── Autonomous self-correction ─────────────────────────────────────────
+
+    def _autonomous_loop(
+        self, original_request: ModifyRequest, last_result: ModifyResult, last_report: Path
+    ) -> ModifyResult:
+        """Read the failure report, diagnose, and restart with a fix."""
+        for cycle in range(1, self._max_autonomous_cycles + 1):
+            logger.info("Autonomous cycle %d/%d", cycle, self._max_autonomous_cycles)
+
+            # Diagnose what went wrong
+            diagnosis = self._diagnose_failure(last_report)
+            if not diagnosis:
+                logger.warning("Could not diagnose failure, stopping autonomous loop")
+                last_result.autonomous_cycles = cycle
+                return last_result
+
+            logger.info("Diagnosis: %s", diagnosis[:200])
+
+            # Build a corrected instruction
+            corrected_instruction = (
+                f"{original_request.instruction}\n\n"
+                f"IMPORTANT CORRECTION from previous failure:\n{diagnosis}"
+            )
+
+            # Reset attempt reports for this cycle
+            self._attempt_reports = []
+
+            corrected_request = ModifyRequest(
+                instruction=corrected_instruction,
+                target_files=original_request.target_files,
+                dry_run=original_request.dry_run,
+            )
+
+            result = self._run_locked(corrected_request)
+            report_path = self._save_report(corrected_request, result)
+            result.report_path = str(report_path)
+            result.autonomous_cycles = cycle
+
+            if result.success:
+                logger.info("Autonomous cycle %d succeeded!", cycle)
+                return result
+
+            last_result = result
+            last_report = report_path
+
+        logger.warning("Autonomous loop exhausted after %d cycles", self._max_autonomous_cycles)
+        return last_result
+
+    def _diagnose_failure(self, report_path: Path) -> Optional[str]:
+        """Read a failure report and produce a diagnosis + fix instruction.
+
+        Uses the best available LLM to analyze the report. This is the
+        'meta-reasoning' step — the agent reasoning about its own failures.
+        """
+        try:
+            report_text = report_path.read_text(encoding="utf-8")
+        except Exception as exc:
+            logger.error("Could not read report %s: %s", report_path, exc)
+            return None
+
+        # Truncate to keep within context limits
+        if len(report_text) > 8000:
+            report_text = report_text[:8000] + "\n... (truncated)"
+
+        diagnosis_prompt = f"""You are a code debugging expert. Analyze this self-modification failure report and provide a concise diagnosis.
+
+FAILURE REPORT:
+{report_text}
+
+Analyze the report and provide:
+1. ROOT CAUSE: What specifically went wrong (syntax error, logic error, missing import, etc.)
+2. FIX INSTRUCTIONS: Exact instructions for a code-generation LLM to avoid this mistake.
+   Be very specific — e.g. "Do NOT start the file with triple-quotes" or
+   "The em-dash character U+2014 must stay INSIDE a string literal, never outside one."
+
+Keep your response under 500 words. Focus on actionable fix instructions."""
+
+        try:
+            raw = self._call_llm(diagnosis_prompt)
+            return raw.strip() if raw else None
+        except Exception as exc:
+            logger.error("Diagnosis LLM call failed: %s", exc)
+            return None
+
+    # ── Internal orchestration ────────────────────────────────────────────────
+
+    def _run_locked(self, request: ModifyRequest) -> ModifyResult:
+        branch_name = None
+        attempt = 0
+
+        # Skip branch creation — writing files triggers container restarts
+        # which kills the process mid-operation. Work on the current branch.
+        if not os.environ.get("SELF_MODIFY_SKIP_BRANCH"):
+            try:
+                branch_name = self._create_branch()
+            except Exception as exc:
+                logger.warning("Could not create branch: %s (continuing on current)", exc)
+
+        # Resolve target files
+        target_files = request.target_files or self._infer_target_files(
+            request.instruction
+        )
+        if not target_files:
+            return ModifyResult(
+                success=False,
+                error="No target files identified. Specify target_files or use more specific language.",
+                branch_name=branch_name,
+            )
+
+        # Validate paths
+        try:
+            self._validate_paths(target_files)
+        except ValueError as exc:
+            return ModifyResult(success=False, error=str(exc), branch_name=branch_name)
+
+        last_test_output = ""
+        last_llm_response = ""
+        last_syntax_errors: dict[str, str] = {}
+
+        while attempt <= self._max_retries:
+            attempt += 1
+            logger.info(
+                "Self-modify attempt %d/%d: %s",
+                attempt,
+                self._max_retries + 1,
+                request.instruction[:80],
+            )
+
+            # Read current contents
+            file_contents = self._read_files(target_files)
+            if not file_contents:
+                return ModifyResult(
+                    success=False,
+                    error="Could not read any target files.",
+                    branch_name=branch_name,
+                    attempts=attempt,
+                )
+
+            # Generate edits via LLM
+            try:
+                edits, llm_response = self._generate_edits(
+                    request.instruction, file_contents,
+                    prev_test_output=last_test_output if attempt > 1 else None,
+                    prev_syntax_errors=last_syntax_errors if attempt > 1 else None,
+                )
+                last_llm_response = llm_response
+            except Exception as exc:
+                self._attempt_reports.append({
+                    "attempt": attempt,
+                    "phase": "llm_generation",
+                    "error": str(exc),
+                })
+                return ModifyResult(
+                    success=False,
+                    error=f"LLM generation failed: {exc}",
+                    branch_name=branch_name,
+                    attempts=attempt,
+                )
+
+            if not edits:
+                self._attempt_reports.append({
+                    "attempt": attempt,
+                    "phase": "parse_edits",
+                    "error": "No file edits parsed from LLM response",
+                    "llm_response": llm_response,
+                })
+                return ModifyResult(
+                    success=False,
+                    error="LLM produced no file edits.",
+                    llm_response=llm_response,
+                    branch_name=branch_name,
+                    attempts=attempt,
+                )
+
+            # Syntax validation — check BEFORE writing to disk
+            syntax_errors = self._validate_syntax(edits)
+            if syntax_errors:
+                last_syntax_errors = syntax_errors
+                error_summary = "; ".join(
+                    f"{fp}: {err}" for fp, err in syntax_errors.items()
+                )
+                logger.warning("Syntax errors in LLM output: %s", error_summary)
+                self._attempt_reports.append({
+                    "attempt": attempt,
+                    "phase": "syntax_validation",
+                    "error": error_summary,
+                    "edits_content": {fp: content for fp, content in edits.items()},
+                    "llm_response": llm_response,
+                })
+                # Don't write — go straight to retry
+                continue
+
+            last_syntax_errors = {}
+
+            if request.dry_run:
+                self._attempt_reports.append({
+                    "attempt": attempt,
+                    "phase": "dry_run",
+                    "edits": {fp: content[:500] + "..." if len(content) > 500 else content
+                              for fp, content in edits.items()},
+                    "llm_response": llm_response,
+                })
+                return ModifyResult(
+                    success=True,
+                    files_changed=list(edits.keys()),
+                    llm_response=llm_response,
+                    branch_name=branch_name,
+                    attempts=attempt,
+                )
+
+            # Write edits
+            written = self._write_files(edits)
+
+            # Run tests
+            test_passed, test_output = self._run_tests()
+            last_test_output = test_output
+
+            # Save per-attempt report
+            self._attempt_reports.append({
+                "attempt": attempt,
+                "phase": "complete",
+                "files_written": written,
+                "edits_content": {fp: content for fp, content in edits.items()},
+                "test_passed": test_passed,
+                "test_output": test_output,
+                "llm_response": llm_response,
+            })
+
+            if test_passed:
+                sha = self._git_commit(
+                    f"self-modify: {request.instruction[:72]}", written
+                )
+                return ModifyResult(
+                    success=True,
+                    files_changed=written,
+                    test_passed=True,
+                    commit_sha=sha,
+                    branch_name=branch_name,
+                    llm_response=llm_response,
+                    attempts=attempt,
+                )
+
+            # Tests failed — revert and maybe retry
+            logger.warning(
+                "Tests failed on attempt %d: %s", attempt, test_output[:200]
+            )
+            self._revert_files(written)
+
+        return ModifyResult(
+            success=False,
+            files_changed=[],
+            test_passed=False,
+            error=f"Tests failed after {attempt} attempt(s).",
+            llm_response=last_llm_response,
+            branch_name=branch_name,
+            attempts=attempt,
+        )
+
+    # ── Syntax validation ──────────────────────────────────────────────────
+
+    def _validate_syntax(self, edits: dict[str, str]) -> dict[str, str]:
+        """Compile-check each .py file edit. Returns {path: error} for failures."""
+        errors: dict[str, str] = {}
+        for fp, content in edits.items():
+            if not fp.endswith(".py"):
+                continue
+            try:
+                compile(content, fp, "exec")
+            except SyntaxError as exc:
+                errors[fp] = f"line {exc.lineno}: {exc.msg}"
+        return errors
+
+    # ── Report saving ─────────────────────────────────────────────────────────
+
+    def _save_report(self, request: ModifyRequest, result: ModifyResult) -> Path:
+        """Save a detailed report to data/self_modify_reports/."""
+        REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+        ts = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+        slug = re.sub(r"[^a-z0-9]+", "_", request.instruction[:40].lower()).strip("_")
+        report_file = REPORTS_DIR / f"{ts}_{slug}.md"
+
+        lines = [
+            f"# Self-Modify Report: {ts}",
+            "",
+            f"**Instruction:** {request.instruction[:200]}",
+            f"**Target files:** {', '.join(request.target_files) or '(auto-detected)'}",
+            f"**Dry run:** {request.dry_run}",
+            f"**Backend:** {self._backend}",
+            f"**Branch:** {result.branch_name or 'N/A'}",
+            f"**Result:** {'SUCCESS' if result.success else 'FAILED'}",
+            f"**Error:** {result.error or 'none'}",
+            f"**Commit:** {result.commit_sha or 'none'}",
+            f"**Attempts:** {result.attempts}",
+            f"**Autonomous cycles:** {result.autonomous_cycles}",
+            "",
+        ]
+
+        for attempt_data in self._attempt_reports:
+            n = attempt_data.get("attempt", "?")
+            phase = attempt_data.get("phase", "?")
+            lines.append(f"## Attempt {n} -- {phase}")
+            lines.append("")
+
+            if "error" in attempt_data and attempt_data.get("phase") != "complete":
+                lines.append(f"**Error:** {attempt_data['error']}")
+                lines.append("")
+
+            if "llm_response" in attempt_data:
+                lines.append("### LLM Response")
+                lines.append("```")
+                lines.append(attempt_data["llm_response"])
+                lines.append("```")
+                lines.append("")
+
+            if "edits_content" in attempt_data:
+                lines.append("### Edits Written")
+                for fp, content in attempt_data["edits_content"].items():
+                    lines.append(f"#### {fp}")
+                    lines.append("```python")
+                    lines.append(content)
+                    lines.append("```")
+                    lines.append("")
+
+            if "test_output" in attempt_data:
+                lines.append(f"### Test Result: {'PASSED' if attempt_data.get('test_passed') else 'FAILED'}")
+                lines.append("```")
+                lines.append(attempt_data["test_output"])
+                lines.append("```")
+                lines.append("")
+
+        report_text = "\n".join(lines)
+        report_file.write_text(report_text, encoding="utf-8")
+        logger.info("Report saved: %s", report_file)
+        return report_file
+
+    # ── Git helpers ───────────────────────────────────────────────────────────
+
+    def _create_branch(self) -> str:
+        """Create and switch to a working branch."""
+        from creative.tools.git_tools import git_branch
+
+        branch_name = f"timmy/self-modify-{int(time.time())}"
+        git_branch(self._repo_path, create=branch_name, switch=branch_name)
+        logger.info("Created branch: %s", branch_name)
+        return branch_name
+
+    def _git_commit(self, message: str, files: list[str]) -> Optional[str]:
+        """Stage files and commit."""
+        from creative.tools.git_tools import git_add, git_commit
+
+        try:
+            git_add(self._repo_path, paths=files)
+            result = git_commit(self._repo_path, message)
+            sha = result.get("sha")
+            logger.info("Committed %s: %s", sha[:8] if sha else "?", message)
+            return sha
+        except Exception as exc:
+            logger.error("Git commit failed: %s", exc)
+            return None
+
+    def _revert_files(self, file_paths: list[str]) -> None:
+        """Restore files from git HEAD."""
+        for fp in file_paths:
+            try:
+                subprocess.run(
+                    ["git", "checkout", "HEAD", "--", fp],
+                    cwd=self._repo_path,
+                    capture_output=True,
+                    timeout=10,
+                )
+            except Exception as exc:
+                logger.error("Failed to revert %s: %s", fp, exc)
+
+    # ── File I/O ──────────────────────────────────────────────────────────────
+
+    def _validate_paths(self, file_paths: list[str]) -> None:
+        """Ensure all paths are within allowed directories."""
+        for fp in file_paths:
+            resolved = (self._repo_path / fp).resolve()
+            repo_resolved = self._repo_path.resolve()
+            if not str(resolved).startswith(str(repo_resolved)):
+                raise ValueError(f"Path escapes repository: {fp}")
+            rel = str(resolved.relative_to(repo_resolved))
+            if not any(rel.startswith(d) for d in self._allowed_dirs):
+                raise ValueError(
+                    f"Path not in allowed directories ({self._allowed_dirs}): {fp}"
+                )
+
+    def _read_files(self, file_paths: list[str]) -> dict[str, str]:
+        """Read file contents from disk."""
+        contents: dict[str, str] = {}
+        for fp in file_paths:
+            full = self._repo_path / fp
+            if not full.is_file():
+                logger.warning("File not found: %s", full)
+                continue
+            if full.stat().st_size > _MAX_FILE_SIZE:
+                logger.warning("File too large, skipping: %s", fp)
+                continue
+            try:
+                contents[fp] = full.read_text(encoding="utf-8")
+            except Exception as exc:
+                logger.warning("Could not read %s: %s", fp, exc)
+        return contents
+
+    def _write_files(self, edits: dict[str, str]) -> list[str]:
+        """Write edited content to disk. Returns paths written."""
+        written: list[str] = []
+        for fp, content in edits.items():
+            full = self._repo_path / fp
+            full.parent.mkdir(parents=True, exist_ok=True)
+            full.write_text(content, encoding="utf-8")
+            written.append(fp)
+            logger.info("Wrote %d bytes to %s", len(content), fp)
+        return written
+
+    def _infer_target_files(self, instruction: str) -> list[str]:
+        """Guess which files to modify from the instruction text."""
+        paths = re.findall(r"[\w/._-]+\.py", instruction)
+        if paths:
+            return paths
+
+        keyword_files = {
+            "config": ["src/config.py"],
+            "health": ["src/dashboard/routes/health.py"],
+            "swarm": ["src/swarm/coordinator.py"],
+            "voice": ["src/voice/nlu.py"],
+            "agent": ["src/timmy/agent.py"],
+            "tool": ["src/timmy/tools.py"],
+            "dashboard": ["src/dashboard/app.py"],
+            "prompt": ["src/timmy/prompts.py"],
+        }
+        instruction_lower = instruction.lower()
+        for keyword, files in keyword_files.items():
+            if keyword in instruction_lower:
+                return files
+        return []
+
+    # ── Test runner ───────────────────────────────────────────────────────────
+
+    def _run_tests(self) -> tuple[bool, str]:
+        """Run the test suite. Returns (passed, output)."""
+        try:
+            result = subprocess.run(
+                [sys.executable, "-m", "pytest", "tests/", "-q", "--tb=short"],
+                capture_output=True,
+                text=True,
+                cwd=self._repo_path,
+                timeout=120,
+            )
+            output = (result.stdout + result.stderr).strip()
+            return result.returncode == 0, output
+        except subprocess.TimeoutExpired:
+            return False, "Tests timed out after 120s"
+        except Exception as exc:
+            return False, f"Failed to run tests: {exc}"
+
+    # ── Multi-backend LLM ─────────────────────────────────────────────────────
+
+    def _resolve_backend(self) -> str:
+        """Resolve 'auto' backend to a concrete one."""
+        if self._backend == "auto":
+            api_key = os.environ.get("ANTHROPIC_API_KEY", "")
+            if api_key:
+                return "anthropic"
+            return "ollama"
+        return self._backend
+
+    def _call_llm(self, prompt: str) -> str:
+        """Route a prompt to the configured LLM backend. Returns raw text."""
+        backend = self._resolve_backend()
+
+        if backend == "anthropic":
+            return self._call_anthropic(prompt)
+        else:
+            return self._call_ollama(prompt)
+
+    def _call_anthropic(self, prompt: str) -> str:
+        """Call Claude via the Anthropic SDK."""
+        import anthropic
+
+        api_key = os.environ.get("ANTHROPIC_API_KEY", "")
+        if not api_key:
+            raise RuntimeError("ANTHROPIC_API_KEY not set — cannot use anthropic backend")
+
+        client = anthropic.Anthropic(api_key=api_key)
+        message = client.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=4096,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return message.content[0].text
+
+    def _call_ollama(self, prompt: str) -> str:
+        """Call the local Ollama instance via Agno."""
+        from agno.agent import Agent
+        from agno.models.ollama import Ollama
+
+        agent = Agent(
+            name="SelfModify",
+            model=Ollama(id=settings.ollama_model, host=settings.ollama_url),
+            markdown=False,
+        )
+        run_result = agent.run(prompt, stream=False)
+        return run_result.content if hasattr(run_result, "content") else str(run_result)
+
+    # ── LLM interaction ───────────────────────────────────────────────────────
+
+    def _generate_edits(
+        self,
+        instruction: str,
+        file_contents: dict[str, str],
+        prev_test_output: Optional[str] = None,
+        prev_syntax_errors: Optional[dict[str, str]] = None,
+    ) -> tuple[dict[str, str], str]:
+        """Ask the LLM to generate file edits.
+
+        Returns (edits_dict, raw_llm_response).
+        """
+        # Build the prompt
+        files_block = ""
+        for fp, content in file_contents.items():
+            files_block += f"\n<FILE path=\"{fp}\">\n{content}\n</FILE>\n"
+
+        retry_context = ""
+        if prev_test_output:
+            retry_context += f"""
+PREVIOUS ATTEMPT FAILED with test errors:
+<TEST_OUTPUT>
+{prev_test_output[:2000]}
+</TEST_OUTPUT>
+Fix the issues shown above.
+"""
+        if prev_syntax_errors:
+            errors_text = "\n".join(f"  {fp}: {err}" for fp, err in prev_syntax_errors.items())
+            retry_context += f"""
+PREVIOUS ATTEMPT HAD SYNTAX ERRORS (code was rejected before writing):
+{errors_text}
+
+You MUST produce syntactically valid Python. Run through the code mentally
+and make sure all strings are properly terminated, all indentation is correct,
+and there are no invalid characters outside of string literals.
+"""
+
+        prompt = f"""You are a precise code modification agent. Edit source files according to the instruction.
+
+INSTRUCTION: {instruction}
+
+CURRENT FILES:
+{files_block}
+{retry_context}
+OUTPUT FORMAT — wrap each modified file like this:
+
+<MODIFIED path="filepath">
+complete file content here
+</MODIFIED>
+
+CRITICAL RULES:
+- Output the COMPLETE file content, not just changed lines
+- Keep ALL existing functionality unless told to remove it
+- The output must be syntactically valid Python — verify mentally before outputting
+- Preserve all special characters (unicode, em-dashes, etc.) exactly as they appear in the original
+- Do NOT wrap the file content in triple-quotes or markdown code fences
+- Do NOT start the file content with \"\"\" — that would turn the code into a string literal
+- Follow the existing code style
+
+Generate the modified files now:"""
+
+        raw = self._call_llm(prompt)
+
+        # Parse <MODIFIED path="..."> ... </MODIFIED> blocks
+        edits = {}
+        xml_re = re.compile(
+            r'<MODIFIED\s+path=["\'](.+?)["\']\s*>\n?(.*?)</MODIFIED>',
+            re.DOTALL,
+        )
+        for match in xml_re.finditer(raw):
+            filepath = match.group(1).strip()
+            content = match.group(2)
+            # Strip trailing whitespace but keep a final newline
+            content = content.rstrip() + "\n"
+            edits[filepath] = content
+
+        # Fallback: try the old delimiter format
+        if not edits:
+            for match in _FILE_BLOCK_RE.finditer(raw):
+                filepath = match.group(1).strip()
+                content = match.group(2).rstrip() + "\n"
+                edits[filepath] = content
+
+        # Last resort: single file + code block
+        if not edits and len(file_contents) == 1:
+            only_path = next(iter(file_contents))
+            code_match = re.search(r"```(?:python)?\n(.*?)```", raw, re.DOTALL)
+            if code_match:
+                edits[only_path] = code_match.group(1).rstrip() + "\n"
+
+        return edits, raw

src/self_coding/self_tdd/__init__.py

@@ -0,0 +1 @@
+"""Self-TDD — Continuous test watchdog with regression alerting."""

src/self_coding/self_tdd/watchdog.py

@@ -0,0 +1,71 @@
+"""Self-TDD Watchdog — polls pytest on a schedule and reports regressions.
+
+Run in a terminal alongside your normal dev work:
+
+    self-tdd watch
+    self-tdd watch --interval 30
+
+The watchdog runs silently while tests pass. When a regression appears it
+prints the full short-traceback output so you can see exactly what broke.
+No files are modified; no commits are made. Ctrl-C to stop.
+"""
+
+import subprocess
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+import typer
+
+# Project root is three levels up from src/self_tdd/watchdog.py
+PROJECT_ROOT = Path(__file__).parent.parent.parent
+
+app = typer.Typer(help="Self-TDD watchdog — continuous test runner")
+
+
+def _run_tests() -> tuple[bool, str]:
+    """Run the test suite and return (passed, combined_output)."""
+    result = subprocess.run(
+        [sys.executable, "-m", "pytest", "tests/", "-q", "--tb=short"],
+        capture_output=True,
+        text=True,
+        cwd=PROJECT_ROOT,
+        timeout=60,
+    )
+    return result.returncode == 0, (result.stdout + result.stderr).strip()
+
+
+@app.command()
+def watch(
+    interval: int = typer.Option(60, "--interval", "-i", help="Seconds between test runs"),
+) -> None:
+    """Poll pytest continuously and print regressions as they appear."""
+    typer.echo(f"Self-TDD watchdog started — polling every {interval}s. Ctrl-C to stop.")
+    last_passed: bool | None = None
+
+    try:
+        while True:
+            passed, output = _run_tests()
+            stamp = datetime.now().strftime("%H:%M:%S")
+
+            if passed:
+                if last_passed is not True:
+                    typer.secho(f"[{stamp}] All tests passing.", fg=typer.colors.GREEN)
+            else:
+                typer.secho(f"[{stamp}] Regression detected:", fg=typer.colors.RED)
+                typer.echo(output)
+
+            last_passed = passed
+            time.sleep(interval)
+
+    except KeyboardInterrupt:
+        typer.echo("\nWatchdog stopped.")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

src/self_coding/upgrades/__init__.py

@@ -0,0 +1 @@
+"""Upgrades — System upgrade queue and execution pipeline."""

src/self_coding/upgrades/models.py

@@ -0,0 +1,331 @@
+"""Database models for Self-Upgrade Approval Queue."""
+
+import json
+import sqlite3
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+DB_PATH = Path("data/swarm.db")
+
+
+class UpgradeStatus(str, Enum):
+    """Status of an upgrade proposal."""
+    PROPOSED = "proposed"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    APPLIED = "applied"
+    FAILED = "failed"
+    EXPIRED = "expired"
+
+
+@dataclass
+class Upgrade:
+    """A self-modification upgrade proposal."""
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    status: UpgradeStatus = UpgradeStatus.PROPOSED
+    
+    # Timestamps
+    proposed_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    approved_at: Optional[str] = None
+    applied_at: Optional[str] = None
+    rejected_at: Optional[str] = None
+    
+    # Proposal details
+    branch_name: str = ""
+    description: str = ""
+    files_changed: list[str] = field(default_factory=list)
+    diff_preview: str = ""
+    
+    # Test results
+    test_passed: bool = False
+    test_output: str = ""
+    
+    # Execution results
+    error_message: Optional[str] = None
+    approved_by: Optional[str] = None
+
+
+def _get_conn() -> sqlite3.Connection:
+    """Get database connection with schema initialized."""
+    DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(DB_PATH))
+    conn.row_factory = sqlite3.Row
+    
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS upgrades (
+            id TEXT PRIMARY KEY,
+            status TEXT NOT NULL DEFAULT 'proposed',
+            proposed_at TEXT NOT NULL,
+            approved_at TEXT,
+            applied_at TEXT,
+            rejected_at TEXT,
+            branch_name TEXT NOT NULL,
+            description TEXT NOT NULL,
+            files_changed TEXT,  -- JSON array
+            diff_preview TEXT,
+            test_passed INTEGER DEFAULT 0,
+            test_output TEXT,
+            error_message TEXT,
+            approved_by TEXT
+        )
+        """
+    )
+    
+    # Indexes
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_upgrades_status ON upgrades(status)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_upgrades_proposed ON upgrades(proposed_at)")
+    
+    conn.commit()
+    return conn
+
+
+def create_upgrade(
+    branch_name: str,
+    description: str,
+    files_changed: list[str],
+    diff_preview: str,
+    test_passed: bool = False,
+    test_output: str = "",
+) -> Upgrade:
+    """Create a new upgrade proposal.
+    
+    Args:
+        branch_name: Git branch name for the upgrade
+        description: Human-readable description
+        files_changed: List of files that would be modified
+        diff_preview: Short diff preview for review
+        test_passed: Whether tests passed on the branch
+        test_output: Test output text
+    
+    Returns:
+        The created Upgrade
+    """
+    upgrade = Upgrade(
+        branch_name=branch_name,
+        description=description,
+        files_changed=files_changed,
+        diff_preview=diff_preview,
+        test_passed=test_passed,
+        test_output=test_output,
+    )
+    
+    conn = _get_conn()
+    conn.execute(
+        """
+        INSERT INTO upgrades (id, status, proposed_at, branch_name, description,
+                            files_changed, diff_preview, test_passed, test_output)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            upgrade.id,
+            upgrade.status.value,
+            upgrade.proposed_at,
+            upgrade.branch_name,
+            upgrade.description,
+            json.dumps(files_changed),
+            upgrade.diff_preview,
+            int(test_passed),
+            test_output,
+        ),
+    )
+    conn.commit()
+    conn.close()
+    
+    return upgrade
+
+
+def get_upgrade(upgrade_id: str) -> Optional[Upgrade]:
+    """Get upgrade by ID."""
+    conn = _get_conn()
+    row = conn.execute(
+        "SELECT * FROM upgrades WHERE id = ?", (upgrade_id,)
+    ).fetchone()
+    conn.close()
+    
+    if not row:
+        return None
+    
+    return Upgrade(
+        id=row["id"],
+        status=UpgradeStatus(row["status"]),
+        proposed_at=row["proposed_at"],
+        approved_at=row["approved_at"],
+        applied_at=row["applied_at"],
+        rejected_at=row["rejected_at"],
+        branch_name=row["branch_name"],
+        description=row["description"],
+        files_changed=json.loads(row["files_changed"]) if row["files_changed"] else [],
+        diff_preview=row["diff_preview"] or "",
+        test_passed=bool(row["test_passed"]),
+        test_output=row["test_output"] or "",
+        error_message=row["error_message"],
+        approved_by=row["approved_by"],
+    )
+
+
+def list_upgrades(
+    status: Optional[UpgradeStatus] = None,
+    limit: int = 100,
+) -> list[Upgrade]:
+    """List upgrades, optionally filtered by status."""
+    conn = _get_conn()
+    
+    if status:
+        rows = conn.execute(
+            "SELECT * FROM upgrades WHERE status = ? ORDER BY proposed_at DESC LIMIT ?",
+            (status.value, limit),
+        ).fetchall()
+    else:
+        rows = conn.execute(
+            "SELECT * FROM upgrades ORDER BY proposed_at DESC LIMIT ?",
+            (limit,),
+        ).fetchall()
+    
+    conn.close()
+    
+    return [
+        Upgrade(
+            id=r["id"],
+            status=UpgradeStatus(r["status"]),
+            proposed_at=r["proposed_at"],
+            approved_at=r["approved_at"],
+            applied_at=r["applied_at"],
+            rejected_at=r["rejected_at"],
+            branch_name=r["branch_name"],
+            description=r["description"],
+            files_changed=json.loads(r["files_changed"]) if r["files_changed"] else [],
+            diff_preview=r["diff_preview"] or "",
+            test_passed=bool(r["test_passed"]),
+            test_output=r["test_output"] or "",
+            error_message=r["error_message"],
+            approved_by=r["approved_by"],
+        )
+        for r in rows
+    ]
+
+
+def approve_upgrade(upgrade_id: str, approved_by: str = "dashboard") -> Optional[Upgrade]:
+    """Approve an upgrade proposal."""
+    now = datetime.now(timezone.utc).isoformat()
+    
+    conn = _get_conn()
+    cursor = conn.execute(
+        """
+        UPDATE upgrades 
+        SET status = ?, approved_at = ?, approved_by = ?
+        WHERE id = ? AND status = ?
+        """,
+        (UpgradeStatus.APPROVED.value, now, approved_by, upgrade_id, UpgradeStatus.PROPOSED.value),
+    )
+    conn.commit()
+    updated = cursor.rowcount > 0
+    conn.close()
+    
+    if not updated:
+        return None
+    
+    return get_upgrade(upgrade_id)
+
+
+def reject_upgrade(upgrade_id: str) -> Optional[Upgrade]:
+    """Reject an upgrade proposal."""
+    now = datetime.now(timezone.utc).isoformat()
+    
+    conn = _get_conn()
+    cursor = conn.execute(
+        """
+        UPDATE upgrades 
+        SET status = ?, rejected_at = ?
+        WHERE id = ? AND status = ?
+        """,
+        (UpgradeStatus.REJECTED.value, now, upgrade_id, UpgradeStatus.PROPOSED.value),
+    )
+    conn.commit()
+    updated = cursor.rowcount > 0
+    conn.close()
+    
+    if not updated:
+        return None
+    
+    return get_upgrade(upgrade_id)
+
+
+def mark_applied(upgrade_id: str) -> Optional[Upgrade]:
+    """Mark upgrade as successfully applied."""
+    now = datetime.now(timezone.utc).isoformat()
+    
+    conn = _get_conn()
+    cursor = conn.execute(
+        """
+        UPDATE upgrades 
+        SET status = ?, applied_at = ?
+        WHERE id = ? AND status = ?
+        """,
+        (UpgradeStatus.APPLIED.value, now, upgrade_id, UpgradeStatus.APPROVED.value),
+    )
+    conn.commit()
+    updated = cursor.rowcount > 0
+    conn.close()
+    
+    if not updated:
+        return None
+    
+    return get_upgrade(upgrade_id)
+
+
+def mark_failed(upgrade_id: str, error_message: str) -> Optional[Upgrade]:
+    """Mark upgrade as failed."""
+    conn = _get_conn()
+    cursor = conn.execute(
+        """
+        UPDATE upgrades 
+        SET status = ?, error_message = ?
+        WHERE id = ? AND status = ?
+        """,
+        (UpgradeStatus.FAILED.value, error_message, upgrade_id, UpgradeStatus.APPROVED.value),
+    )
+    conn.commit()
+    updated = cursor.rowcount > 0
+    conn.close()
+    
+    if not updated:
+        return None
+    
+    return get_upgrade(upgrade_id)
+
+
+def get_pending_count() -> int:
+    """Get count of pending (proposed) upgrades."""
+    conn = _get_conn()
+    row = conn.execute(
+        "SELECT COUNT(*) as count FROM upgrades WHERE status = ?",
+        (UpgradeStatus.PROPOSED.value,),
+    ).fetchone()
+    conn.close()
+    return row["count"]
+
+
+def prune_old_upgrades(older_than_days: int = 30) -> int:
+    """Delete old completed upgrades."""
+    from datetime import timedelta
+    
+    cutoff = (datetime.now(timezone.utc) - timedelta(days=older_than_days)).isoformat()
+    
+    conn = _get_conn()
+    cursor = conn.execute(
+        """
+        DELETE FROM upgrades 
+        WHERE proposed_at < ? AND status IN ('applied', 'rejected', 'failed')
+        """,
+        (cutoff,),
+    )
+    deleted = cursor.rowcount
+    conn.commit()
+    conn.close()
+    
+    return deleted

src/self_coding/upgrades/queue.py

@@ -0,0 +1,285 @@
+"""Upgrade Queue management - bridges self-modify loop with approval workflow."""
+
+import logging
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from self_coding.upgrades.models import (
+    Upgrade,
+    UpgradeStatus,
+    create_upgrade,
+    get_upgrade,
+    approve_upgrade,
+    reject_upgrade,
+    mark_applied,
+    mark_failed,
+)
+
+logger = logging.getLogger(__name__)
+
+PROJECT_ROOT = Path(__file__).parent.parent.parent
+
+
+class UpgradeQueue:
+    """Manages the upgrade approval and application workflow."""
+    
+    @staticmethod
+    def propose(
+        branch_name: str,
+        description: str,
+        files_changed: list[str],
+        diff_preview: str,
+        test_passed: bool = False,
+        test_output: str = "",
+    ) -> Upgrade:
+        """Propose a new upgrade for approval.
+        
+        This is called by the self-modify loop when it generates changes.
+        The upgrade is created in 'proposed' state and waits for human approval.
+        
+        Args:
+            branch_name: Git branch with the changes
+            description: What the upgrade does
+            files_changed: List of modified files
+            diff_preview: Short diff for review
+            test_passed: Whether tests passed
+            test_output: Test output
+        
+        Returns:
+            The created Upgrade proposal
+        """
+        upgrade = create_upgrade(
+            branch_name=branch_name,
+            description=description,
+            files_changed=files_changed,
+            diff_preview=diff_preview,
+            test_passed=test_passed,
+            test_output=test_output,
+        )
+        
+        logger.info(
+            "Upgrade proposed: %s (%s) - %d files",
+            upgrade.id[:8],
+            branch_name,
+            len(files_changed),
+        )
+        
+        # Log to event log
+        try:
+            from swarm.event_log import log_event, EventType
+            log_event(
+                EventType.SYSTEM_INFO,
+                source="upgrade_queue",
+                data={
+                    "upgrade_id": upgrade.id,
+                    "branch": branch_name,
+                    "description": description,
+                    "test_passed": test_passed,
+                },
+            )
+        except Exception:
+            pass
+        
+        return upgrade
+    
+    @staticmethod
+    def approve(upgrade_id: str, approved_by: str = "dashboard") -> Optional[Upgrade]:
+        """Approve an upgrade proposal.
+        
+        Called from dashboard when user clicks "Approve".
+        Does NOT apply the upgrade - that happens separately.
+        
+        Args:
+            upgrade_id: The upgrade to approve
+            approved_by: Who approved it (for audit)
+        
+        Returns:
+            Updated Upgrade or None if not found/not in proposed state
+        """
+        upgrade = approve_upgrade(upgrade_id, approved_by)
+        
+        if upgrade:
+            logger.info("Upgrade approved: %s by %s", upgrade_id[:8], approved_by)
+        
+        return upgrade
+    
+    @staticmethod
+    def reject(upgrade_id: str) -> Optional[Upgrade]:
+        """Reject an upgrade proposal.
+        
+        Called from dashboard when user clicks "Reject".
+        Cleans up the branch.
+        
+        Args:
+            upgrade_id: The upgrade to reject
+        
+        Returns:
+            Updated Upgrade or None
+        """
+        upgrade = reject_upgrade(upgrade_id)
+        
+        if upgrade:
+            logger.info("Upgrade rejected: %s", upgrade_id[:8])
+            
+            # Clean up branch
+            try:
+                subprocess.run(
+                    ["git", "branch", "-D", upgrade.branch_name],
+                    cwd=PROJECT_ROOT,
+                    capture_output=True,
+                    check=False,
+                )
+            except Exception as exc:
+                logger.warning("Failed to delete branch %s: %s", upgrade.branch_name, exc)
+        
+        return upgrade
+    
+    @staticmethod
+    def apply(upgrade_id: str) -> tuple[bool, str]:
+        """Apply an approved upgrade.
+        
+        This is the critical operation that actually modifies the codebase:
+        1. Checks out the branch
+        2. Runs tests
+        3. If tests pass: merges to main
+        4. Updates upgrade status
+        
+        Args:
+            upgrade_id: The approved upgrade to apply
+        
+        Returns:
+            (success, message) tuple
+        """
+        upgrade = get_upgrade(upgrade_id)
+        
+        if not upgrade:
+            return False, "Upgrade not found"
+        
+        if upgrade.status != UpgradeStatus.APPROVED:
+            return False, f"Upgrade not approved (status: {upgrade.status.value})"
+        
+        logger.info("Applying upgrade: %s (%s)", upgrade_id[:8], upgrade.branch_name)
+        
+        try:
+            # 1. Checkout branch
+            result = subprocess.run(
+                ["git", "checkout", upgrade.branch_name],
+                cwd=PROJECT_ROOT,
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                mark_failed(upgrade_id, f"Checkout failed: {result.stderr}")
+                return False, f"Failed to checkout branch: {result.stderr}"
+            
+            # 2. Run tests
+            result = subprocess.run(
+                ["python", "-m", "pytest", "tests/", "-x", "-q"],
+                cwd=PROJECT_ROOT,
+                capture_output=True,
+                text=True,
+                timeout=120,
+            )
+            
+            if result.returncode != 0:
+                mark_failed(upgrade_id, f"Tests failed: {result.stdout}\n{result.stderr}")
+                # Switch back to main
+                subprocess.run(["git", "checkout", "main"], cwd=PROJECT_ROOT, check=False)
+                return False, "Tests failed"
+            
+            # 3. Merge to main
+            result = subprocess.run(
+                ["git", "checkout", "main"],
+                cwd=PROJECT_ROOT,
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                mark_failed(upgrade_id, f"Failed to checkout main: {result.stderr}")
+                return False, "Failed to checkout main"
+            
+            result = subprocess.run(
+                ["git", "merge", "--no-ff", upgrade.branch_name, "-m", f"Apply upgrade: {upgrade.description}"],
+                cwd=PROJECT_ROOT,
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                mark_failed(upgrade_id, f"Merge failed: {result.stderr}")
+                return False, "Merge failed"
+            
+            # 4. Mark as applied
+            mark_applied(upgrade_id)
+            
+            # 5. Clean up branch
+            subprocess.run(
+                ["git", "branch", "-d", upgrade.branch_name],
+                cwd=PROJECT_ROOT,
+                capture_output=True,
+                check=False,
+            )
+            
+            logger.info("Upgrade applied successfully: %s", upgrade_id[:8])
+            return True, "Upgrade applied successfully"
+            
+        except subprocess.TimeoutExpired:
+            mark_failed(upgrade_id, "Tests timed out")
+            subprocess.run(["git", "checkout", "main"], cwd=PROJECT_ROOT, check=False)
+            return False, "Tests timed out"
+            
+        except Exception as exc:
+            error_msg = str(exc)
+            mark_failed(upgrade_id, error_msg)
+            subprocess.run(["git", "checkout", "main"], cwd=PROJECT_ROOT, check=False)
+            return False, f"Error: {error_msg}"
+    
+    @staticmethod
+    def get_full_diff(upgrade_id: str) -> str:
+        """Get full git diff for an upgrade.
+        
+        Args:
+            upgrade_id: The upgrade to get diff for
+        
+        Returns:
+            Git diff output
+        """
+        upgrade = get_upgrade(upgrade_id)
+        if not upgrade:
+            return "Upgrade not found"
+        
+        try:
+            result = subprocess.run(
+                ["git", "diff", "main..." + upgrade.branch_name],
+                cwd=PROJECT_ROOT,
+                capture_output=True,
+                text=True,
+            )
+            return result.stdout if result.returncode == 0 else result.stderr
+        except Exception as exc:
+            return f"Error getting diff: {exc}"
+
+
+# Convenience functions for self-modify loop
+def propose_upgrade_from_loop(
+    branch_name: str,
+    description: str,
+    files_changed: list[str],
+    diff: str,
+    test_output: str = "",
+) -> Upgrade:
+    """Called by self-modify loop to propose an upgrade.
+    
+    Tests are expected to have been run by the loop before calling this.
+    """
+    # Check if tests passed from output
+    test_passed = "passed" in test_output.lower() or " PASSED " in test_output
+    
+    return UpgradeQueue.propose(
+        branch_name=branch_name,
+        description=description,
+        files_changed=files_changed,
+        diff_preview=diff[:2000],  # First 2000 chars
+        test_passed=test_passed,
+        test_output=test_output,
+    )