openreflex 0.1.0__py3-none-any.whl

openreflex/__init__.py

@@ -0,0 +1,3 @@
+"""Ambient, local execution intelligence."""
+
+__version__ = "0.1.0"

openreflex/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

openreflex/benchmark.py

@@ -0,0 +1,225 @@
+"""Simulated benchmark: baseline agent vs. the same agent guided by OpenReflex.
+
+What this measures: whether the real engine (hook events in, contexts/alerts out) learns from noisy outcomes
+fast enough to route toward better strategies, surface useful files, and cut failure loops, and how that
+compounds over repeated task families.
+
+What this does NOT measure: real-world agent gains. Every environment parameter below (strategy success
+rates, call counts, how much a file hint saves, how often an agent heeds an alert) is an explicit assumption
+in SIMULATION_ASSUMPTIONS. Validate claims with A/B runs on real tasks before quoting them.
+"""
+
+import random
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from statistics import mean
+
+from .engine import Engine
+from .routing import utility
+from .store import Store
+
+SIMULATION_ASSUMPTIONS = {
+    "baseline_strategy": "inspect-first 60%, otherwise uniform among the three strategies (no memory)",
+    "guided_follow_rate": 0.8,
+    "file_hint_search_reduction": "search/read calls drop from 6-9 to 2-3 when the context names relevant files",
+    "alert_heed_rate": 0.7,
+    "failure_loop": "probability per task is family-specific; an unheeded loop runs 5 extra failing attempts",
+    "seconds_per_call": 25,
+    "tokens_per_call": {"search": 400, "read": 1500, "edit": 300, "test": 1100},
+}
+STRATEGIES = ("inspect-first", "test-first", "incremental")
+
+
+@dataclass(frozen=True)
+class Family:
+    name: str
+    templates: tuple[str, ...]
+    success: dict[str, float]    # true success probability per strategy
+    extra_calls: dict[str, int]  # strategy-specific extra work in this area of the codebase
+    loop_probability: float
+    files: tuple[str, ...]
+
+
+FAMILIES = (
+    Family("auth-expiry", ("Fix the login bug where expired {x} tokens are accepted",
+                           "Fix expired {x} token still accepted by the login check"),
+           {"inspect-first": .55, "test-first": .9, "incremental": .7}, {"inspect-first": 2, "test-first": 1, "incremental": 5},
+           .35, ("src/auth/session.py", "tests/test_session.py")),
+    Family("webhook-signature", ("Fix failing {x} webhook signature verification",
+                                 "Fix {x} webhook signature check rejecting valid payloads"),
+           {"inspect-first": .8, "test-first": .6, "incremental": .65}, {"inspect-first": 0, "test-first": 6, "incremental": 4},
+           .3, ("src/payments/webhooks.py",)),
+    Family("billing-refactor", ("Refactor the {x} billing module into smaller services",
+                                "Refactor {x} billing calculations out of the invoice controller"),
+           {"inspect-first": .5, "test-first": .6, "incremental": .88}, {"inspect-first": 3, "test-first": 4, "incremental": 2},
+           .2, ("src/billing/invoice.py", "src/billing/tax.py", "src/billing/service.py")),
+    Family("csv-export", ("Add {x} CSV export to the reports page",
+                          "Build a {x} CSV export endpoint for monthly reports"),
+           {"inspect-first": .85, "test-first": .8, "incremental": .8}, {"inspect-first": 0, "test-first": 3, "incremental": 5},
+           .1, ("src/reports/export.py", "src/reports/views.py")),
+    Family("parser-tests", ("Increase test coverage for the {x} config parser",
+                            "Add tests covering {x} edge cases in the config parser"),
+           {"inspect-first": .75, "test-first": .9, "incremental": .8}, {"inspect-first": 2, "test-first": 0, "incremental": 3},
+           .15, ("src/config/parser.py", "tests/test_parser.py")),
+)
+VARIANTS = ("admin", "mobile", "legacy", "tenant", "guest", "partner", "nightly", "api")
+TOKENS = SIMULATION_ASSUMPTIONS["tokens_per_call"]
+
+
+def true_utility(family: Family, strategy: str, search_calls: float = 7.5) -> float:
+    calls = search_calls + 4 + family.extra_calls[strategy] + family.loop_probability * 2.5
+    return utility(family.success[strategy], calls * 25, calls, calls * 800, 0.12, 0, 0.93)
+
+
+def oracle(family: Family) -> str:
+    return max(STRATEGIES, key=lambda s: true_utility(family, s))
+
+
+class Agent:
+    def __init__(self, guided: bool, rng: random.Random, engine: Engine, clock: list[float]):
+        self.guided, self.rng, self.engine, self.clock = guided, rng, engine, clock
+        self.calls = 0
+
+    def tick(self, seconds: float = 25):
+        self.clock[0] += seconds * self.rng.uniform(0.6, 1.4)
+
+    def tool(self, session: str, name: str, arguments: dict, success: bool = True, error: str | None = None,
+             category: str = "read") -> str | None:
+        self.calls += 1
+        self.tick()
+        tool_id = f"{session}-{self.calls}"
+        warning = self.engine.tool_start("sim", session, tool_id, name, arguments)
+        self.tick(3)
+        alert = self.engine.tool_end("sim", session, tool_id, name, arguments, success, error, TOKENS[category] * 4)
+        return alert or warning
+
+
+def episode(agent: Agent, family: Family, index: int) -> dict:
+    rng, session = agent.rng, f"{family.name}-{index}"
+    prompt = rng.choice(family.templates).format(x=rng.choice(VARIANTS))
+    context = agent.engine.prompt("sim", session, prompt)
+    engine_pick = agent.engine.store.get(agent.engine.store.latest("sim", session).recommended_path_id).strategy
+
+    habit = "inspect-first" if rng.random() < 0.6 else rng.choice(STRATEGIES)
+    strategy = engine_pick if agent.guided and rng.random() < SIMULATION_ASSUMPTIONS["guided_follow_rate"] else habit
+    hinted = agent.guided and context is not None and any(f in context for f in family.files)
+
+    start_calls, tokens = agent.calls, 0
+    area = family.files[0].rsplit("/", 1)[0]
+    for i in range(rng.randint(2, 3) if hinted else rng.randint(6, 9)):
+        category = "search" if i % 2 == 0 else "read"
+        name, args = ("Grep", {"pattern": f"{family.name}-{i}", "path": area}) if category == "search" else \
+            ("Read", {"file_path": family.files[i % len(family.files)]})
+        agent.tool(session, name, args, category=category)
+        tokens += TOKENS[category]
+
+    test = ("Bash", {"command": f"pytest tests -k {family.name}"})
+    edit = ("Edit", {"file_path": family.files[0], "old_string": "a", "new_string": str(index)})
+    succeeded = rng.random() < family.success[strategy]
+    failure = f"AssertionError: {family.name} check failed"
+
+    def run(name_args, category, success=True, error=None):
+        nonlocal tokens
+        tokens += TOKENS[category]
+        return agent.tool(session, *name_args, success=success, error=error, category=category)
+
+    if strategy == "test-first":
+        run(test, "test", False, failure)
+    for i in range(family.extra_calls[strategy]):
+        run(("Read", {"file_path": family.files[i % len(family.files)], "offset": i * 50}), "read")
+    slices = 3 if strategy == "incremental" else 1
+    for i in range(slices):
+        run(edit, "edit")
+        if i < slices - 1:
+            run(test, "test")
+
+    if rng.random() < family.loop_probability:
+        for attempt in range(5):
+            alert = run(test, "test", False, failure)
+            run(edit, "edit")
+            if alert and agent.guided and rng.random() < SIMULATION_ASSUMPTIONS["alert_heed_rate"]:
+                break
+    run(test, "test", succeeded, None if succeeded else failure)
+    agent.engine.stop("sim", session)
+    agent.tick(120)
+
+    best = oracle(family)
+    return {"family": family.name, "strategy": strategy, "recommended": engine_pick, "oracle": best,
+            "success": succeeded, "tool_calls": agent.calls - start_calls, "tokens": tokens,
+            "seconds": (agent.calls - start_calls) * SIMULATION_ASSUMPTIONS["seconds_per_call"],
+            "regret": round(true_utility(family, best) - true_utility(family, strategy), 4)}
+
+
+def run_arm(guided: bool, episodes: int, seed: int) -> list[dict]:
+    rng = random.Random(seed)
+    with tempfile.TemporaryDirectory() as directory:
+        clock = [1_700_000_000.0]
+        engine = Engine(Path(directory), Store(Path(directory) / "bench.sqlite3"), clock=lambda: clock[0])
+        try:
+            agent = Agent(guided, rng, engine, clock)
+            return [episode(agent, FAMILIES[i % len(FAMILIES)] if i % 3 else rng.choice(FAMILIES), i)
+                    for i in range(episodes)]
+        finally:
+            engine.close()
+
+
+def summarize(results: list[dict]) -> dict:
+    quarter = max(1, len(results) // 4)
+    second_half = results[len(results) // 2:]
+    return {
+        "tool_calls": round(mean(r["tool_calls"] for r in results), 2),
+        "tokens": round(mean(r["tokens"] for r in results), 1),
+        "seconds": round(mean(r["seconds"] for r in results), 1),
+        "success_rate": round(mean(r["success"] for r in results), 3),
+        "regret_first_quarter": round(mean(r["regret"] for r in results[:quarter]), 4),
+        "regret_last_quarter": round(mean(r["regret"] for r in results[-quarter:]), 4),
+        "routing_agreement_second_half": round(mean(r["recommended"] == r["oracle"] for r in second_half), 3),
+    }
+
+
+def run_benchmark(episodes: int = 150, seeds: int = 3) -> dict:
+    per_seed = []
+    for seed in range(seeds):
+        per_seed.append({"seed": seed, "baseline": summarize(run_arm(False, episodes, seed)),
+                         "guided": summarize(run_arm(True, episodes, seed))})
+    keys = per_seed[0]["baseline"].keys()
+    baseline = {k: round(mean(s["baseline"][k] for s in per_seed), 4) for k in keys}
+    guided = {k: round(mean(s["guided"][k] for s in per_seed), 4) for k in keys}
+
+    def change(key):
+        return round((guided[key] - baseline[key]) / baseline[key], 3) if baseline[key] else None
+
+    return {
+        "kind": "simulation",
+        "episodes_per_arm": episodes, "seeds": seeds,
+        "assumptions": SIMULATION_ASSUMPTIONS,
+        "oracle_best_strategy": {f.name: oracle(f) for f in FAMILIES},
+        "baseline": baseline, "guided": guided,
+        "relative_change": {"tool_calls": change("tool_calls"), "tokens": change("tokens"), "time": change("seconds"),
+                            "success_rate_points": round(guided["success_rate"] - baseline["success_rate"], 3)},
+        "targets": {"tool_calls": -0.20, "tokens": -0.20, "time": -0.15, "routing_agreement": 0.70},
+        "per_seed": per_seed,
+    }
+
+
+def format_report(report: dict) -> str:
+    b, g, c = report["baseline"], report["guided"], report["relative_change"]
+    rows = [
+        ("tool calls / task", b["tool_calls"], g["tool_calls"], f"{c['tool_calls']:+.0%}", "-20..-30%"),
+        ("output tokens / task", b["tokens"], g["tokens"], f"{c['tokens']:+.0%}", "-20%"),
+        ("time / task (s)", b["seconds"], g["seconds"], f"{c['time']:+.0%}", "-15%"),
+        ("success rate", b["success_rate"], g["success_rate"], f"{c['success_rate_points']:+.3f} pts", ">= baseline"),
+        ("regret, first quarter", b["regret_first_quarter"], g["regret_first_quarter"], "", ""),
+        ("regret, last quarter", b["regret_last_quarter"], g["regret_last_quarter"], "", "declining"),
+        ("routing agreement (2nd half)", "-", g["routing_agreement_second_half"], "", "> 0.70"),
+    ]
+    lines = [f"SIMULATED benchmark - {report['episodes_per_arm']} tasks/arm x {report['seeds']} seeds "
+             "(assumption-driven; not evidence of real-world gains)", ""]
+    lines.append(f"{'metric':30} {'baseline':>10} {'guided':>10} {'change':>12}  target")
+    def cell(value):
+        return f"{value:,.3f}".rstrip("0").rstrip(".") if isinstance(value, float) else str(value)
+
+    for name, base, guide, delta, target in rows:
+        lines.append(f"{name:30} {cell(base):>10} {cell(guide):>10} {delta:>12}  {target}")
+    return "\n".join(lines)

openreflex/cli.py

@@ -0,0 +1,238 @@
+import argparse
+import json
+import shutil
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+from .project import approval, approve, home, project_root, revoke
+
+AGENT_CHOICES = ["claude-code", "codex", "cursor", "opencode"]
+
+
+def _project(value: str | None) -> Path:
+    # An unexpanded ${VAR} placeholder from an agent config means "not provided".
+    return project_root(None if not value or "${" in value else value)
+
+
+def _utf8_stdio() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+
+def cmd_hook(args) -> int:
+    from .hooks import safe_handle
+
+    raw = sys.stdin.buffer.read().decode("utf-8", errors="replace")
+    output = safe_handle(args.agent, args.event or "", raw)
+    if output:
+        sys.stdout.write(output)
+        sys.stdout.flush()
+    return 0  # never block the agent
+
+
+def cmd_mcp(args) -> int:
+    from .mcp_server import serve
+
+    serve(None if not args.project or "${" in args.project else args.project)
+    return 0
+
+
+def cmd_approve(args) -> int:
+    project = _project(args.project)
+    record = approve(project)
+    print(f"OpenReflex enabled for {project} (since {time.strftime('%Y-%m-%d %H:%M', time.localtime(record['approved_at']))}).")
+    return 0
+
+
+def cmd_revoke(args) -> int:
+    project = _project(args.project)
+    print(f"Capture disabled for {project}." if revoke(project) else f"{project} was not enabled.")
+    return 0
+
+
+def cmd_install(args) -> int:
+    from .install import install
+
+    project = _project(args.project)
+    changes = install(args.agent, project, dry_run=args.dry_run)
+    verb = "Would write" if args.dry_run else "Wrote"
+    for change in changes:
+        print(f"{verb} {change}")
+    if not changes:
+        print("Already installed; nothing to change.")
+    if not args.dry_run:
+        print(f"Enabled for {project}.")
+        if args.agent == "codex":
+            print("Codex asks you to trust new hooks once: open /hooks in Codex and approve the OpenReflex entries.")
+    if shutil.which("openreflex") is None:
+        print("Warning: `openreflex` is not on PATH; hooks will not run. Install with `uv tool install .` or `pipx install .`.")
+    return 0
+
+
+def cmd_status(args) -> int:
+    from .engine import Engine
+    from .metrics import project_metrics
+
+    project = _project(args.project)
+    record = approval(project)
+    engine = Engine(project)
+    try:
+        data = project_metrics(engine, record)
+    finally:
+        engine.close()
+    data["enabled"] = record is not None
+    if args.json:
+        print(json.dumps(data, indent=2))
+        return 0
+    reuse, regret, routing = data["experience_reuse"], data["execution_regret"], data["routing"]
+    eff = data["efficiency_observational"]
+    print(f"OpenReflex {__version__} - {project}")
+    print(f"  enabled: {data['enabled']}   agents: {', '.join(data['engagement']['agents']) or '-'}")
+    print(f"  tasks: {data['engagement']['tasks']}   experiences: {data['engagement']['experiences']}   lessons: {data['lessons']}")
+    print(f"  first session captured: {data['activation']['first_session_captured']}   "
+          f"seconds to first task: {data['activation']['seconds_to_first_task']}")
+    print(f"  tasks benefiting from prior experience: {reuse['benefit_rate']}")
+    print(f"  success rate (known outcomes): {data['outcomes']['success_rate']}   verified: {data['outcomes']['verified']}")
+    print(f"  tool calls with vs without prior experience: {eff['with_prior_experience']['tool_calls']} vs "
+          f"{eff['without_prior_experience']['tool_calls']} (observational)")
+    print(f"  mean execution regret: {regret['mean']}   routing agreement: {routing['agreement']}")
+    print(f"  live alerts: {data['live_alerts'] or '-'}")
+    return 0
+
+
+def cmd_context(args) -> int:
+    from .engine import Engine
+
+    engine = Engine(_project(args.project))
+    try:
+        print(engine.preview(args.task))
+    finally:
+        engine.close()
+    return 0
+
+
+def cmd_doctor(args) -> int:
+    from .store import database_path
+
+    project = _project(args.project)
+    checks = [
+        ("openreflex on PATH", shutil.which("openreflex") is not None),
+        ("project enabled", approval(project) is not None),
+        ("database exists", database_path(project).exists()),
+        ("Claude Code hooks (project)", "openreflex hook" in _read(project / ".claude" / "settings.json")),
+        ("Codex hooks (project)", "openreflex hook" in _read(project / ".codex" / "hooks.json")),
+        ("Cursor hooks (project)", "openreflex hook" in _read(project / ".cursor" / "hooks.json")),
+        ("OpenCode plugin (project)", (project / ".opencode" / "plugins" / "openreflex.ts").exists()),
+    ]
+    print(f"Project: {project}\nData:    {database_path(project)}")
+    for name, ok in checks:
+        print(f"  [{'ok' if ok else '--'}] {name}")
+    log = home() / "logs" / "errors.log"
+    if log.exists():
+        tail = log.read_text(encoding="utf-8", errors="replace").splitlines()[-5:]
+        print("Recent hook errors:\n  " + "\n  ".join(tail))
+    return 0
+
+
+def _read(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
+def cmd_forget(args) -> int:
+    from .store import database_path
+
+    project = _project(args.project)
+    directory = database_path(project).parent
+    if not args.yes:
+        print(f"This deletes all OpenReflex data for {project} ({directory}). Re-run with --yes to confirm.")
+        return 1
+    shutil.rmtree(directory, ignore_errors=True)
+    print(f"Deleted {directory}.")
+    return 0
+
+
+def cmd_benchmark(args) -> int:
+    from .benchmark import format_report, run_benchmark
+
+    report = run_benchmark(episodes=args.episodes, seeds=args.seeds)
+    print(format_report(report))
+    if args.out:
+        Path(args.out).write_text(json.dumps(report, indent=2), encoding="utf-8")
+        print(f"\nWrote {args.out}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="openreflex", description="Ambient execution intelligence for coding agents.")
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    hook = sub.add_parser("hook", help="Handle a lifecycle hook (JSON on stdin); used by agent configs")
+    # No `choices`: argparse exits 2 on bad input, and exit code 2 means "block" to Claude Code and Codex.
+    hook.add_argument("agent", help=", ".join(AGENT_CHOICES))
+    hook.add_argument("event", nargs="?")
+    hook.set_defaults(func=cmd_hook)
+
+    mcp = sub.add_parser("mcp", help="Run the MCP stdio server")
+    mcp.add_argument("--project")
+    mcp.set_defaults(func=cmd_mcp)
+
+    for name, func, text in (("approve", cmd_approve, "Enable capture for a project"),
+                             ("revoke", cmd_revoke, "Disable capture for a project"),
+                             ("doctor", cmd_doctor, "Check installation and recent hook errors")):
+        command = sub.add_parser(name, help=text)
+        command.add_argument("--project")
+        command.set_defaults(func=func)
+
+    install = sub.add_parser("install", help="Write project hook + MCP config for an agent and enable the project")
+    install.add_argument("agent", choices=AGENT_CHOICES)
+    install.add_argument("--project")
+    install.add_argument("--dry-run", action="store_true")
+    install.set_defaults(func=cmd_install)
+
+    status = sub.add_parser("status", help="Show capture, reuse, regret, and routing metrics")
+    status.add_argument("--project")
+    status.add_argument("--json", action="store_true")
+    status.set_defaults(func=cmd_status)
+
+    context = sub.add_parser("context", help="Preview the Execution Context for a task description")
+    context.add_argument("task")
+    context.add_argument("--project")
+    context.set_defaults(func=cmd_context)
+
+    forget = sub.add_parser("forget", help="Delete all captured data for a project")
+    forget.add_argument("--project")
+    forget.add_argument("--yes", action="store_true")
+    forget.set_defaults(func=cmd_forget)
+
+    bench = sub.add_parser("benchmark", help="Run the simulated baseline-vs-guided benchmark suite")
+    bench.add_argument("--episodes", type=int, default=150)
+    bench.add_argument("--seeds", type=int, default=3)
+    bench.add_argument("--out", default="benchmark-results.json")
+    bench.set_defaults(func=cmd_benchmark)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    _utf8_stdio()
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["hook"]:
+        # Hook invocations must never fail loudly or return a blocking exit code, whatever the arguments.
+        try:
+            return cmd_hook(argparse.Namespace(agent=argv[1] if len(argv) > 1 else "", event=argv[2] if len(argv) > 2 else ""))
+        except BaseException:  # noqa: BLE001
+            return 0
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

openreflex/detect.py

@@ -0,0 +1,82 @@
+"""Live inefficiency detection. Pure functions over the current execution's minimized telemetry.
+
+Alerts are deliberately conservative: each kind fires at most once per execution (context growth may
+escalate once more after compaction), and any alert respects a cooldown, so the agent is only
+interrupted when replanning is justified by evidence rather than by a single slow step.
+"""
+
+from dataclasses import dataclass
+
+from .models import CandidatePath, Execution, ToolCall
+from .privacy import PROGRESS
+
+COOLDOWN_SECONDS = 180
+REPEAT_THRESHOLD = 3
+FAILURE_LOOP_THRESHOLD = 3
+STAGNATION_CALLS = 15
+STAGNATION_SECONDS = 600
+CONTEXT_FLOOR_TOKENS = 30000
+
+
+@dataclass(frozen=True)
+class Alert:
+    kind: str
+    severity: float
+    detail: str
+
+
+def detect(execution: Execution, calls: list[ToolCall], recommended: CandidatePath | None, now: float) -> list[Alert]:
+    alerts: list[Alert] = []
+    finished = [c for c in calls if c.status != "running"]
+
+    recent = calls[-10:]
+    counts: dict[str, int] = {}
+    for call in recent:
+        counts[call.fingerprint] = counts.get(call.fingerprint, 0) + 1
+    repeated = max(counts.values(), default=0)
+    if repeated >= REPEAT_THRESHOLD:
+        name = next(c.name for c in reversed(recent) if counts[c.fingerprint] == repeated)
+        alerts.append(Alert("repeated_action", 0.6, f"the same {name} call ran {repeated}x in the last {len(recent)} calls"))
+
+    streak = 0
+    for call in reversed(finished):
+        if call.status != "failure":
+            break
+        streak += 1
+    same_signature = [c.error_signature for c in finished[-5:] if c.status == "failure" and c.error_signature]
+    top_signature = max(set(same_signature), key=same_signature.count, default=None)
+    if streak >= FAILURE_LOOP_THRESHOLD:
+        alerts.append(Alert("failure_loop", 0.9, f"{streak} consecutive tool failures"))
+    elif top_signature and same_signature.count(top_signature) >= FAILURE_LOOP_THRESHOLD:
+        alerts.append(Alert("failure_loop", 0.8, f"\"{top_signature}\" recurred {same_signature.count(top_signature)}x in 5 calls"))
+
+    since_progress = [c for c in calls if c.started_at > execution.last_progress_at]
+    idle = now - execution.last_progress_at
+    # Exploration and Q&A legitimately read without editing; only judge stagnation once implementation has
+    # begun (an edit or check was attempted), or when reading has gone on far longer than any plan needs.
+    implementing = any(c.category in PROGRESS for c in calls)
+    threshold = STAGNATION_CALLS if implementing else 2 * STAGNATION_CALLS
+    if len(since_progress) >= threshold or (implementing and idle >= STAGNATION_SECONDS and len(since_progress) >= 5):
+        kinds = sorted({c.category for c in since_progress})
+        alerts.append(Alert("stagnation", 0.7, f"{len(since_progress)} calls over {idle / 60:.0f} min without a "
+                                               f"successful edit or check (only {', '.join(kinds)})"))
+
+    budget = max(CONTEXT_FLOOR_TOKENS, 2 * (recommended.context_tokens if recommended else 8000))
+    if execution.output_tokens_estimate > budget or execution.compactions:
+        reason = "context was compacted" if execution.compactions else \
+            f"~{execution.output_tokens_estimate // 1000}k tokens of tool output (budget ~{int(budget) // 1000}k)"
+        alerts.append(Alert("context_growth", 0.5, reason))
+
+    if recommended and len(calls) > max(30, 2.5 * recommended.tool_calls) and not any(
+            c.category in PROGRESS and c.status == "success" for c in calls[-8:]):
+        alerts.append(Alert("over_budget", 0.5, f"{len(calls)} tool calls vs ~{recommended.tool_calls:.0f} expected"))
+    return alerts
+
+
+def select(execution: Execution, alerts: list[Alert], now: float) -> Alert | None:
+    """Choose at most one alert that is new for this execution and outside the cooldown."""
+    if now - execution.last_alert_at < COOLDOWN_SECONDS:
+        return None
+    fresh = [a for a in alerts if a.kind not in execution.alerts or
+             (a.kind == "context_growth" and execution.alerts.count(a.kind) < 1 + min(execution.compactions, 1))]
+    return max(fresh, key=lambda a: a.severity, default=None)