@misterhuydo/sentinel 1.4.89 → 1.4.90

package/python/sentinel/sentinel_dev.py

@@ -0,0 +1,490 @@
+"""
+sentinel_dev.py — Autonomous Developer Claude agent for Sentinel self-improvement.
+
+Dev Claude runs alongside Boss but independently. It watches dev-tasks/ for
+requests to improve Sentinel itself — new features, bug fixes, refactors — and
+executes them by running Claude Code against the Sentinel source repository.
+
+Invocation sources:
+  - Boss (dev_task tool) → slack-<uuid>.txt in dev-tasks/
+  - Fix engine (BOSS_ESCALATE output) → bot-<fp>-<ts>.txt in dev-tasks/
+  - Admin (manual file drop) → any .txt in dev-tasks/
+
+After a successful task:
+  - Commits changes to the Sentinel source repo
+  - If SENTINEL_DEV_AUTO_PUBLISH=true: bumps patch version + npm publish + sentinel upgrade
+  - Posts Slack notification with summary
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+import subprocess
+import time
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .config_loader import SentinelConfig
+from .dev_watcher import DevTask
+from .fix_engine import _claude_cmd, _run_claude_attempt, _write_claude_log, _is_auth_error
+from .notify import slack_alert
+
+logger = logging.getLogger(__name__)
+
+# Dev tasks are bigger than fix tasks — allow 15 minutes
+_DEV_TIMEOUT = 900
+
+_BOSS_ESCALATE_PREFIX = "BOSS_ESCALATE:"
+
+
+def _build_dev_prompt(task: DevTask, repo_path: str, past_outcomes: list | None = None) -> str:
+    submitted = f"Submitted by: <@{task.submitter_user_id}>" if task.submitter_user_id else ""
+    escalation_ctx = ""
+    if task.source_fingerprint:
+        escalation_ctx = (
+            f"\nThis task was escalated by the fix engine (error fingerprint: "
+            f"{task.source_fingerprint}) because it required a change to Sentinel itself.\n"
+        )
+
+    memory_ctx = ""
+    if past_outcomes:
+        lines = ["━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+                 "MEMORY — SIMILAR PAST TASKS (learn from these)",
+                 "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"]
+        for o in past_outcomes:
+            lines.append(
+                f"[{o['recorded_at'][:10]}] {o['status'].upper()} — {o['task_type']}: "
+                f"{o['description'][:120]}"
+            )
+            if o.get("outcome_note"):
+                lines.append(f"  Outcome: {o['outcome_note'][:200]}")
+            if o.get("files_changed"):
+                lines.append(f"  Files: {o['files_changed']}")
+        lines.append(
+            "Use these as reference: repeat what worked, avoid what failed or was skipped."
+        )
+        memory_ctx = "\n".join(lines) + "\n\n"
+
+    return (
+        f"You are Sentinel Developer — a fully autonomous AI agent responsible for the\n"
+        f"resiliency, stability, and continuous improvement of the Sentinel DevOps system.\n"
+        f"Sentinel source repository: {repo_path}\n"
+        f"{submitted}\n"
+        f"{escalation_ctx}\n"
+        f"{memory_ctx}"
+        f"TASK TYPE: {task.task_type}\n"
+        f"TASK:\n{task.body}\n\n"
+        f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"
+        f"YOUR ROLE AND AUTHORITY\n"
+        f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"
+        f"You have FULL AUTONOMY within Sentinel's operational scope. This means:\n"
+        f"- Modify any source file in this repo (Python, JS, configs, templates)\n"
+        f"- Edit config files (sentinel.properties, log-configs/, repo-configs/)\n"
+        f"- Install OS packages or CLI tools needed to make Sentinel work\n"
+        f"  (e.g. git, curl, jq, common CI/CD tools — use dnf/yum/apt as appropriate)\n"
+        f"- Run scripts, restart services, or apply system-level fixes within scope\n"
+        f"- Commit and push changes to the Sentinel source repository\n"
+        f"You do NOT need permission for any of the above. Act, don't ask.\n"
+        f"\n"
+        f"You work WITH Sentinel Boss, not under it. The relationship:\n"
+        f"  Humans → Boss (Boss obeys humans)\n"
+        f"  Boss ↔ Dev Claude (peer agents — you can ask Boss, Boss can task you)\n"
+        f"  Dev Claude → Sentinel (full autonomy)\n"
+        f"\n"
+        f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"
+        f"SENTINEL CODEBASE OVERVIEW\n"
+        f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"
+        f"- Entry point: sentinel/main.py (asyncio poll loop + dev poll loop)\n"
+        f"- Config: sentinel/config_loader.py (SentinelConfig, LogSourceConfig, RepoConfig)\n"
+        f"- Slack bot + tools: sentinel/sentinel_boss.py\n"
+        f"- Fix engine: sentinel/fix_engine.py (Claude Code subprocess runner)\n"
+        f"- Git ops: sentinel/git_manager.py\n"
+        f"- Log fetching: sentinel/log_fetcher.py, sentinel/log_syncer.py\n"
+        f"- Log parsing: sentinel/log_parser.py\n"
+        f"- Issue queue: sentinel/issue_watcher.py\n"
+        f"- Dev task queue + self-repair: sentinel/dev_watcher.py\n"
+        f"- Dev Claude agent: sentinel/sentinel_dev.py\n"
+        f"- State + memory: sentinel/state_store.py (SQLite, incl. dev_history)\n"
+        f"- Notifications: sentinel/notify.py\n"
+        f"- CLI package: cli/ (Node.js, npm package @misterhuydo/sentinel)\n"
+        f"- Templates: cli/templates/ (sentinel.properties, workspace-sentinel.properties)\n"
+        f"\n"
+        f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"
+        f"INSTRUCTIONS\n"
+        f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"
+        f"1. Explore the relevant source files before making changes.\n"
+        f"2. Implement the task. Follow existing patterns:\n"
+        f"   - Same error handling style (try/except with logger.error)\n"
+        f"   - Same Slack notification pattern (slack_alert from notify.py)\n"
+        f"   - Same dataclass + file-watcher pattern (see issue_watcher.py)\n"
+        f"   - Same async/executor pattern for blocking work (see main.py)\n"
+        f"3. Syntax check each modified Python file:\n"
+        f"   python3 -m py_compile <file>\n"
+        f"4. Check modified JS/Node files:\n"
+        f"   node --check <file>\n"
+        f"5. Commit all changes:\n"
+        f"   git add -A -- sentinel/ cli/   (or be more selective)\n"
+        f"   git commit -m \"{task.task_type}(dev-agent): <concise summary> [sentinel-dev]\"\n"
+        f"6. If this is a meaningful new feature or fix (not a trivial chore), output on its own line:\n"
+        f"   VERSION_BUMPED: <new_version>\n"
+        f"   (The version is in cli/package.json — bump the patch number)\n"
+        f"7. End your response with a brief summary of what changed (max 10 lines).\n"
+        f"\n"
+        f"BOUNDARIES (the only things outside your scope):\n"
+        f"- Never touch managed application repos (the repos Sentinel monitors — not this repo)\n"
+        f"- Do NOT run npm publish — Sentinel handles publishing after your commit\n"
+        f"- Never take actions that affect systems outside this server and Sentinel's own repos\n"
+        f"\n"
+        f"WHEN YOU NEED INFORMATION OR HUMAN DECISION:\n"
+        f"- If you have a specific question that only a human admin can answer (e.g. credentials\n"
+        f"  that must be provided, a business decision, or approval for an irreversible action):\n"
+        f"  output exactly: ASK_BOSS: <your question>\n"
+        f"  Sentinel Boss will relay it to the admin team and bring you the answer.\n"
+        f"  Use this sparingly — try to solve problems autonomously first.\n"
+        f"- If the task is genuinely impossible (e.g. requires physical hardware, or contradicts\n"
+        f"  a hard architectural constraint):\n"
+        f"  output exactly: SKIP: <reason>\n"
+    )
+
+
+_ASK_BOSS_RETRIES = 2  # how many times Dev Claude may ask Boss per task
+
+
+def _consult_boss(question: str, task_context: str, cfg: "SentinelConfig") -> str:
+    """
+    Route a Dev Claude question to the Boss LLM.
+    Boss answers from its knowledge of Sentinel, or indicates it needs human input.
+    Returns Boss's answer as a string.
+    """
+    if not cfg.anthropic_api_key:
+        return "(Boss unavailable — no API key configured)"
+    try:
+        import anthropic as _anthropic
+        _client = _anthropic.Anthropic(api_key=cfg.anthropic_api_key)
+        _resp = _client.messages.create(
+            model="claude-opus-4-6",
+            max_tokens=600,
+            system=(
+                "You are Sentinel Boss — the operational orchestrator of the Sentinel DevOps system. "
+                "You are answering a question from Dev Claude, your peer AI agent who maintains "
+                "Sentinel's source code autonomously. Dev Claude has full authority within Sentinel's "
+                "operational scope and only asks you when it truly needs information it cannot find itself.\n\n"
+                "Answer concisely and directly. If you know the answer from Sentinel's architecture or "
+                "standard practices, give it. If the question requires a human admin decision (e.g. "
+                "secret credentials, budget approval, irreversible production changes), reply with:\n"
+                "NEEDS_HUMAN: <brief reason>\n\n"
+                "Context of the task Dev Claude is working on:\n"
+                f"{task_context[:400]}"
+            ),
+            messages=[{"role": "user", "content": f"Dev Claude asks: {question}"}],
+        )
+        return _resp.content[0].text.strip() if _resp.content else "(no answer from Boss)"
+    except Exception as _e:
+        logger.warning("Dev agent: Boss consultation failed: %s", _e)
+        return f"(Boss consultation failed: {_e})"
+
+
+def _extract_version_bumped(output: str) -> str | None:
+    """Parse VERSION_BUMPED: <version> from Claude output."""
+    m = re.search(r'^VERSION_BUMPED:\s*(\S+)', output, re.MULTILINE | re.IGNORECASE)
+    return m.group(1) if m else None
+
+
+def _extract_summary(output: str) -> str:
+    """Extract the last meaningful paragraph from Claude output (not tool-use lines)."""
+    lines = output.splitlines()
+    substantive = [
+        l for l in lines
+        if l.strip() and not re.match(r'^[⏺⎆●✦✓✗]', l.strip())
+        and not l.strip().startswith("VERSION_BUMPED")
+    ]
+    if not substantive:
+        return output[-400:].strip()
+    return "\n".join(substantive[-12:])[:500]
+
+
+def _run_npm_publish(repo_path: str, env: dict, on_progress=None) -> bool:
+    """Run npm publish from cli/ directory. Returns True on success."""
+    cli_dir = Path(repo_path) / "cli"
+    if not cli_dir.exists():
+        logger.warning("Dev agent: cli/ not found at %s", cli_dir)
+        return False
+    if on_progress:
+        try:
+            on_progress(":rocket: Publishing to npm...")
+        except Exception:
+            pass
+    try:
+        r = subprocess.run(
+            ["npm", "publish", "--access", "public"],
+            cwd=str(cli_dir),
+            capture_output=True, text=True, timeout=120, env=env,
+        )
+        if r.returncode == 0:
+            logger.info("Dev agent: npm publish succeeded")
+            return True
+        logger.error("Dev agent: npm publish failed (rc=%d): %s", r.returncode, r.stderr[:300])
+        return False
+    except Exception as e:
+        logger.error("Dev agent: npm publish error: %s", e)
+        return False
+
+
+
+def _dev_progress_from_line(line: str) -> str | None:
+    """Convert Claude Code tool-use lines to human-readable dev progress messages."""
+    _TOOL_RE = re.compile(r'^[⏺⎆●✦]\s*(\w+)\s*\((.{0,120})', re.UNICODE)
+    m = _TOOL_RE.match(line.strip())
+    if not m:
+        return None
+    tool, args = m.group(1), m.group(2).rstrip(')')
+    if tool == "Bash":
+        cmd = args.strip()
+        if re.search(r'py_compile|node.*--check', cmd):
+            return ":white_check_mark: Syntax checking..."
+        if re.search(r'\bgit\b.*\bcommit\b', cmd):
+            return ":floppy_disk: Committing changes..."
+        if re.search(r'\bgit\b.*\bpush\b', cmd):
+            return ":arrow_up: Pushing to remote..."
+        if re.search(r'\bnpm\b.*\bpublish\b', cmd):
+            return ":rocket: Publishing to npm..."
+        if re.search(r'\bgrep\b|\bfind\b|\bls\b|\bcat\b', cmd):
+            return ":mag: Exploring codebase..."
+        if re.search(r'\bgit\b.*\badd\b|\bgit\b.*\bstatus\b', cmd):
+            return ":pencil2: Staging changes..."
+    elif tool in ("Edit", "MultiEdit"):
+        fname = args.split(",")[0].strip().split("/")[-1]
+        return f":pencil2: Editing `{fname}`" if fname else ":pencil2: Editing file..."
+    elif tool == "Write":
+        fname = args.split(",")[0].strip().split("/")[-1]
+        return f":pencil2: Writing `{fname}`" if fname else None
+    elif tool == "Read":
+        fname = args.split(",")[0].strip().split("/")[-1]
+        return f":eyes: Reading `{fname}`" if fname else None
+    return None
+
+
+def run_dev_task(
+    task: DevTask,
+    cfg: SentinelConfig,
+    store,
+    on_progress=None,
+) -> tuple[str, str]:
+    """
+    Execute a dev task against the Sentinel source repo using Claude Code.
+
+    Returns (status, detail) where status is one of:
+      "done"        — task completed and committed
+      "published"   — task done + npm published + upgrade triggered
+      "needs_human" — Claude flagged for human review
+      "skip"        — Claude explicitly declined
+      "error"       — runtime failure
+
+    detail is: new_version string (if published), reason (if skip/needs_human), or "".
+    """
+    repo_path = cfg.sentinel_dev_repo_path
+    if not repo_path or not Path(repo_path).exists():
+        logger.error("Dev agent: SENTINEL_DEV_REPO_PATH not set or does not exist: %r", repo_path)
+        return "error", f"SENTINEL_DEV_REPO_PATH not configured or missing: {repo_path}"
+
+    # Fetch similar past outcomes from DB memory to include in prompt
+    past_outcomes = []
+    if store:
+        try:
+            past_outcomes = store.get_similar_dev_outcomes(task.body, limit=5)
+        except Exception as _e:
+            logger.debug("Dev agent: could not fetch past outcomes: %s", _e)
+
+    prompt = _build_dev_prompt(task, repo_path, past_outcomes=past_outcomes or None)
+
+    # Set up environment (same pattern as fix_engine.generate_fix)
+    base_env = {**os.environ}
+    if cfg.anthropic_api_key:
+        base_env["ANTHROPIC_API_KEY"] = cfg.anthropic_api_key
+
+    # Log path
+    claude_logs_dir = Path(cfg.workspace_dir).parent / "logs" / "claude"
+    ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S")
+    claude_log_path = claude_logs_dir / f"dev-{task.fingerprint[:8]}-{ts}.log"
+
+    if on_progress:
+        try:
+            on_progress(":brain: Dev Claude exploring codebase...")
+        except Exception:
+            pass
+
+    def _record(status: str, note: str = "", files: str = "", commit: str = "") -> None:
+        if store:
+            try:
+                store.record_dev_outcome(
+                    fingerprint=task.fingerprint,
+                    task_type=task.task_type,
+                    source=task.source,
+                    description=task.body,
+                    status=status,
+                    outcome_note=note,
+                    files_changed=files,
+                    commit_hash=commit,
+                )
+            except Exception as _e:
+                logger.debug("Dev agent: could not record outcome: %s", _e)
+
+    def _run_claude(current_prompt: str) -> "tuple[str, bool]":
+        """Run one Claude attempt with auth fallback. Raises FileNotFoundError if binary missing."""
+        if cfg.claude_pro_for_tasks:
+            out, tout = _run_claude_attempt(
+                cfg.claude_code_bin, current_prompt,
+                env=base_env, cwd=repo_path,
+                claude_log_path=claude_log_path,
+                on_progress=lambda line: _fire_progress(line, on_progress),
+            )
+            if _is_auth_error(out):
+                logger.warning("Dev agent: OAuth auth failed, trying API key")
+                out, tout = _run_claude_attempt(
+                    cfg.claude_code_bin, current_prompt,
+                    env={**base_env, "ANTHROPIC_API_KEY": cfg.anthropic_api_key or ""},
+                    cwd=repo_path,
+                    claude_log_path=claude_log_path,
+                    on_progress=lambda line: _fire_progress(line, on_progress),
+                )
+            return out, tout
+        return _run_claude_attempt(
+            cfg.claude_code_bin, current_prompt,
+            env=base_env, cwd=repo_path,
+            claude_log_path=claude_log_path,
+            on_progress=lambda line: _fire_progress(line, on_progress),
+        )
+
+    # ── Run Dev Claude, with Boss consultation loop for ASK_BOSS: ────────────
+    current_prompt = prompt
+    boss_exchanges: list[str] = []  # accumulated Q&A to append to prompt on retry
+
+    for attempt in range(_ASK_BOSS_RETRIES + 1):
+        try:
+            output, timed_out = _run_claude(current_prompt)
+        except FileNotFoundError:
+            logger.error("Dev agent: claude binary not found: %s", cfg.claude_code_bin)
+            return "error", f"Claude CLI not found at {cfg.claude_code_bin}"
+
+        if timed_out:
+            logger.error("Dev agent: Claude timed out for task %s", task.fingerprint[:8])
+            return "error", "Dev Claude timed out after 15 minutes."
+
+        stripped = output.strip()
+
+        # Dev Claude has a question → consult Boss → retry with answer
+        if stripped.upper().startswith("ASK_BOSS:"):
+            question = stripped[len("ASK_BOSS:"):].strip()
+            logger.info(
+                "Dev agent: ASK_BOSS (attempt %d/%d): %s",
+                attempt + 1, _ASK_BOSS_RETRIES + 1, question[:200],
+            )
+            if on_progress:
+                try:
+                    on_progress(f":speech_balloon: Asking Boss: _{question[:120]}_")
+                except Exception:
+                    pass
+            boss_answer = _consult_boss(question, task.body, cfg)
+            logger.info("Dev agent: Boss answered: %s", boss_answer[:200])
+
+            # If Boss itself needs human input, surface it
+            if boss_answer.upper().startswith("NEEDS_HUMAN:"):
+                human_reason = boss_answer[len("NEEDS_HUMAN:"):].strip()
+                _record("needs_human", note=human_reason[:400])
+                return "needs_human", human_reason
+
+            # Append Q&A to prompt and retry
+            exchange = (
+                f"\nBoss answered your question:\n"
+                f"Q: {question}\n"
+                f"A: {boss_answer}\n"
+                f"Now continue the task with this information.\n"
+            )
+            boss_exchanges.append(exchange)
+            current_prompt = prompt + "\n\n━━ BOSS CONSULTATION HISTORY ━━" + "".join(boss_exchanges)
+            if on_progress:
+                try:
+                    on_progress(":arrows_counterclockwise: Dev Claude resuming with Boss's answer...")
+                except Exception:
+                    pass
+            continue  # retry with enriched prompt
+
+        # Not an ASK_BOSS — process the final output
+        break
+    else:
+        # Exhausted retries — treat as needs_human (Boss couldn't unblock Dev Claude)
+        _record("needs_human", note="Exhausted Boss consultations without completing task")
+        return "needs_human", "Dev Claude could not complete the task after consulting Boss. Human review needed."
+
+    if stripped.upper().startswith("SKIP:"):
+        reason = stripped[5:].strip()
+        logger.info("Dev agent: skipped task %s: %s", task.fingerprint[:8], reason[:200])
+        _record("skip", note=reason[:400])
+        return "skip", reason
+
+    # Parse optional VERSION_BUMPED signal and summary
+    new_version = _extract_version_bumped(output)
+    summary = _extract_summary(output)
+
+    logger.info(
+        "Dev agent: task %s completed (version_bumped=%s)",
+        task.fingerprint[:8], new_version or "no",
+    )
+
+    # Extract files changed from git output in Claude's response (best-effort)
+    _files_re = re.findall(r'\bsentinel/\S+\.py\b|\bcli/\S+\.(?:js|json)\b', output)
+    files_str = ", ".join(dict.fromkeys(_files_re))[:300]
+
+    # Post-execution: publish to npm if configured and version was bumped
+    if cfg.sentinel_dev_auto_publish and new_version:
+        published = _run_npm_publish(repo_path, base_env, on_progress)
+        if published:
+            _record("published", note=summary, files=files_str, commit=new_version)
+            return "published", new_version
+        _record("done", note=summary, files=files_str, commit=new_version)
+        return "done", new_version
+
+    _record("done", note=summary, files=files_str)
+    return "done", new_version or ""
+
+
+def _fire_progress(line: str, on_progress) -> None:
+    """Translate a raw Claude output line to progress and fire the callback."""
+    if on_progress:
+        msg = _dev_progress_from_line(line)
+        if msg:
+            try:
+                on_progress(msg)
+            except Exception:
+                pass
+
+
+def drop_escalation(project_dir: Path, description: str, source: str = "fix_engine/BOSS_ESCALATE",
+                    source_fingerprint: str = "", submitter_user_id: str = "") -> Path:
+    """
+    Create a dev task file for an escalation from a child Claude instance or Boss.
+    Returns the path to the created file.
+    """
+    dev_tasks_dir = project_dir / "dev-tasks"
+    dev_tasks_dir.mkdir(exist_ok=True)
+    ts = int(time.time())
+    fp_part = source_fingerprint[:8] if source_fingerprint else "esc"
+    fname = f"bot-{fp_part}-{ts}.txt"
+    fpath = dev_tasks_dir / fname
+
+    lines = [
+        "TYPE: fix",
+        f"SOURCE: {source}",
+    ]
+    if source_fingerprint:
+        lines.append(f"SOURCE_FINGERPRINT: {source_fingerprint}")
+    if submitter_user_id:
+        lines.append(f"SUBMITTED_BY: ({submitter_user_id})")
+    lines.append(f"SUBMITTED_AT: {datetime.now(timezone.utc).isoformat()}")
+    lines.append("")
+    lines.append(description)
+    fpath.write_text("\n".join(lines), encoding="utf-8")
+    logger.info("Dev escalation dropped: %s", fname)
+    return fpath

package/python/sentinel/state_store.py

@@ -4,6 +4,7 @@ state_store.py — SQLite-backed persistence for errors, fixes, and reports.
 from __future__ import annotations
 
 import json
+import re
 import sqlite3
 import logging
 from contextlib import contextmanager
@@ -556,3 +557,123 @@ class StateStore:
                     "SELECT * FROM errors ORDER BY last_seen DESC"
                 ).fetchall()
         return [dict(r) for r in rows]
+
+    # ── Knowledge cache (ask_codebase results) ────────────────────────────────
+
+    def get_knowledge(self, repo_name: str, question: str) -> "str | None":
+        """Return cached answer for a codebase question, or None if expired/missing."""
+        with self._conn() as conn:
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS knowledge_cache ("
+                "  repo_name  TEXT NOT NULL,"
+                "  question   TEXT NOT NULL,"
+                "  answer     TEXT NOT NULL,"
+                "  expires_at TEXT NOT NULL,"
+                "  PRIMARY KEY (repo_name, question)"
+                ")"
+            )
+            row = conn.execute(
+                "SELECT answer FROM knowledge_cache "
+                "WHERE repo_name=? AND question=? AND expires_at > datetime('now')",
+                (repo_name, question),
+            ).fetchone()
+        return row["answer"] if row else None
+
+    def save_knowledge(self, repo_name: str, question: str, answer: str, ttl_hours: int = 24) -> None:
+        """Cache a codebase question answer with a TTL."""
+        with self._conn() as conn:
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS knowledge_cache ("
+                "  repo_name  TEXT NOT NULL,"
+                "  question   TEXT NOT NULL,"
+                "  answer     TEXT NOT NULL,"
+                "  expires_at TEXT NOT NULL,"
+                "  PRIMARY KEY (repo_name, question)"
+                ")"
+            )
+            conn.execute(
+                "INSERT OR REPLACE INTO knowledge_cache (repo_name, question, answer, expires_at) "
+                "VALUES (?, ?, ?, datetime('now', ? || ' hours'))",
+                (repo_name, question, answer, str(ttl_hours)),
+            )
+
+    # ── Dev Claude memory (self-repair history + learning) ────────────────────
+
+    def _ensure_dev_history(self, conn) -> None:
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS dev_history ("
+            "  fingerprint   TEXT PRIMARY KEY,"
+            "  task_type     TEXT NOT NULL,"
+            "  source        TEXT NOT NULL,"
+            "  description   TEXT NOT NULL,"
+            "  status        TEXT NOT NULL,"
+            "  outcome_note  TEXT NOT NULL DEFAULT '',"
+            "  files_changed TEXT NOT NULL DEFAULT '',"
+            "  commit_hash   TEXT NOT NULL DEFAULT '',"
+            "  recorded_at   TEXT NOT NULL"
+            ")"
+        )
+
+    def record_dev_outcome(
+        self,
+        fingerprint: str,
+        task_type: str,
+        source: str,
+        description: str,
+        status: str,
+        outcome_note: str = "",
+        files_changed: str = "",
+        commit_hash: str = "",
+    ) -> None:
+        """Persist the outcome of a Dev Claude task for future learning."""
+        with self._conn() as conn:
+            self._ensure_dev_history(conn)
+            conn.execute(
+                "INSERT OR REPLACE INTO dev_history "
+                "(fingerprint, task_type, source, description, status, "
+                " outcome_note, files_changed, commit_hash, recorded_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))",
+                (fingerprint, task_type, source, description[:500], status,
+                 outcome_note[:500], files_changed[:300], commit_hash),
+            )
+
+    def get_dev_history(self, limit: int = 20) -> list[dict]:
+        """Return recent Dev Claude task outcomes, newest first."""
+        with self._conn() as conn:
+            self._ensure_dev_history(conn)
+            rows = conn.execute(
+                "SELECT fingerprint, task_type, source, description, status, "
+                "       outcome_note, files_changed, commit_hash, recorded_at "
+                "FROM dev_history ORDER BY recorded_at DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def get_similar_dev_outcomes(self, description: str, limit: int = 5) -> list[dict]:
+        """
+        Return past Dev Claude outcomes whose description overlaps with the given one.
+        Used to give Dev Claude context about similar past fixes before it starts work.
+        """
+        _stop = {"error", "sentinel", "false", "true", "none", "that", "this",
+                 "with", "from", "have", "been", "when", "where", "they", "their"}
+        words = [
+            w.lower() for w in re.findall(r'\b\w{5,}\b', description)
+            if w.lower() not in _stop
+        ]
+        if not words:
+            return []
+        with self._conn() as conn:
+            self._ensure_dev_history(conn)
+            clauses = " OR ".join(["description LIKE ?" for _ in words[:6]])
+            params = [f"%{w}%" for w in words[:6]] + [limit * 3]
+            rows = conn.execute(
+                f"SELECT fingerprint, task_type, status, outcome_note, "
+                f"       description, recorded_at "
+                f"FROM dev_history WHERE ({clauses}) "
+                f"ORDER BY recorded_at DESC LIMIT ?",
+                params,
+            ).fetchall()
+        def _score(r):
+            text = (r["description"] + " " + r["outcome_note"]).lower()
+            return sum(1 for w in words if w in text)
+        return sorted([dict(r) for r in rows], key=_score, reverse=True)[:limit]