ophar 0.1.0__py3-none-any.whl

cli/client.py

@@ -0,0 +1,137 @@
+"""HTTP/WS client with auto-spawn of the local API server (OpenCode-style).
+
+Discovery: state/server/server.json lockfile {pid, port, started_at}.
+If the server is alive (/health) -> connect.
+Otherwise -> spawn uvicorn in the background, wait for /health, write lockfile.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+import websockets
+
+from ophar.paths import get_root
+
+ROOT = get_root()
+STATE_DIR = ROOT / "state" / "server"
+LOCKFILE = STATE_DIR / "server.json"
+PYTHON = sys.executable
+DEFAULT_PORT = 8001
+
+
+def _ensure_state_dir() -> None:
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _read_lockfile() -> dict | None:
+    if not LOCKFILE.exists():
+        return None
+    try:
+        return json.loads(LOCKFILE.read_text())
+    except (json.JSONDecodeError, IOError):
+        return None
+
+
+def _write_lockfile(data: dict) -> None:
+    _ensure_state_dir()
+    LOCKFILE.write_text(json.dumps(data, indent=2))
+
+
+def _is_alive(port: int) -> bool:
+    """Check if the server at 127.0.0.1:<port> responds to /health."""
+    try:
+        resp = httpx.get(f"http://127.0.0.1:{port}/health", timeout=2)
+        return resp.status_code == 200 and resp.json().get("status") == "ok"
+    except Exception:
+        return False
+
+
+def _pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+
+def get_base_url() -> str:
+    """Get the base URL of the API server, spawning it if necessary.
+
+    Returns the base URL (e.g. 'http://127.0.0.1:8000').
+    """
+    lock = _read_lockfile()
+    if lock:
+        port = lock["port"]
+        pid = lock["pid"]
+        if _pid_alive(pid) and _is_alive(port):
+            return f"http://127.0.0.1:{port}"
+
+    # Spawn new server
+    port = int(os.environ.get("OPUS_PORT", str(DEFAULT_PORT)))
+    log_path = STATE_DIR / "server.log"
+
+    env = {**os.environ}
+    cmd = [
+        PYTHON, "-m", "uvicorn", "server.main:app",
+        "--host", "127.0.0.1",
+        "--port", str(port),
+        "--log-level", "warning",
+    ]
+    with open(log_path, "a") as fh:
+        proc = subprocess.Popen(
+            cmd,
+            stdout=fh,
+            stderr=subprocess.STDOUT,
+            env=env,
+            preexec_fn=os.setsid,
+        )
+
+    _write_lockfile({
+        "pid": proc.pid,
+        "port": port,
+        "started_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    })
+
+    # Wait for /health (up to 15s)
+    base = f"http://127.0.0.1:{port}"
+    for _ in range(30):
+        if _is_alive(port):
+            return base
+        time.sleep(0.5)
+
+    raise RuntimeError(f"Server did not start on port {port}. Check {log_path} for errors.")
+
+
+def get_ws_url(path: str) -> str:
+    base = get_base_url()
+    ws_base = base.replace("http://", "ws://")
+    return f"{ws_base}{path}"
+
+
+def api_get(path: str, **params) -> dict | list:
+    base = get_base_url()
+    resp = httpx.get(f"{base}{path}", params=params, timeout=30)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def api_post(path: str, body: dict | None = None) -> dict:
+    base = get_base_url()
+    resp = httpx.post(f"{base}{path}", json=body or {}, timeout=120)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def api_put(path: str, body: dict) -> dict:
+    base = get_base_url()
+    resp = httpx.put(f"{base}{path}", json=body, timeout=30)
+    resp.raise_for_status()
+    return resp.json()

cli/commands/metrics.py

@@ -0,0 +1,59 @@
+"""Metrics commands."""
+
+import time
+
+import typer
+from rich.console import Console
+from rich.live import Live
+from rich.table import Table
+from rich.panel import Panel
+
+from ..client import api_get
+
+app = typer.Typer()
+console = Console()
+
+
+def _render_metrics_table(data: dict) -> Table:
+    raw = data["raw"]
+    table = Table(title="Metrics Snapshot")
+    table.add_column("Metric")
+    table.add_column("Value")
+    table.add_row("[bold]Runs[/]", str(raw.get("runs", "?")))
+    table.add_row("[bold]Work OK Rate[/]", f"{(raw.get('work_ok_rate', 0) or 0) * 100:.1f}%")
+    table.add_row("[bold]Overclaim Rate[/]", f"{(raw.get('overclaim_rate', 0) or 0) * 100:.1f}%")
+    table.add_row("[bold]Composer Tokens[/]", str(raw.get("composer_tokens_total", "?")))
+    q = raw.get("quantiles", {})
+    wc = q.get("wall_clock_s", {})
+    if wc:
+        table.add_row("[bold]Wall (p50/p95)[/]", f"{wc.get('p50', '?')} / {wc.get('p95', '?')}s")
+    opus = raw.get("opus", {})
+    if opus:
+        table.add_row("[bold]Opus Tokens Total[/]", str(opus.get("opus_tokens_total", "?")))
+    return table
+
+
+@app.command()
+def show(
+    json_: bool = typer.Option(False, "--json", help="Raw JSON output"),
+    watch: bool = typer.Option(False, "--watch", help="Live refreshing dashboard"),
+    classes: bool = typer.Option(False, "--classes", help="Breakdown by class"),
+):
+    """View metrics."""
+    if classes:
+        data = api_get("/api/metrics/classes")
+        console.print_json(data=data)
+        return
+    if watch:
+        with Live(refresh_per_second=0.3) as live:
+            while True:
+                data = api_get("/api/metrics")
+                live.update(_render_metrics_table(data))
+                time.sleep(3)
+        return
+    if json_:
+        data = api_get("/api/metrics")
+        console.print_json(data=data)
+        return
+    data = api_get("/api/metrics")
+    console.print(_render_metrics_table(data))

cli/commands/settings.py

@@ -0,0 +1,25 @@
+"""Settings commands."""
+
+import typer
+from rich.console import Console
+
+from ..client import api_get, api_put
+
+console = Console()
+
+
+def settings_get():
+    """Show current settings."""
+    data = api_get("/api/settings")
+    for k, v in sorted(data.items()):
+        console.print(f"[bold]{k}[/] = {v}")
+
+
+def settings_set(key: str = typer.Argument(...), value: str = typer.Argument(...)):
+    """Set a setting (e.g. opctl settings-set MAX_ITERATIONS 5)."""
+    try:
+        parsed = int(value)
+    except ValueError:
+        parsed = value
+    result = api_put("/api/settings", {key: parsed})
+    console.print(f"[green]{key}[/] → {result.get(key)}")

cli/commands/system.py

@@ -0,0 +1,76 @@
+"""System commands: serve, stop, status, reconcile.
+
+The orchestrator is NOT a CLI command - it is reached through the `ophar`
+MCP server (instructions + pipeline:// resources + tools). Run `claude` and the
+registered MCP server makes the session an orchestrator. There is no `opctl chat`.
+"""
+
+import os
+import signal
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ..client import get_base_url, api_get, api_post
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command()
+def serve():
+    """Start the API server explicitly (normally auto-spawned)."""
+    base = get_base_url()
+    console.print(f"[green]Server running at {base}[/]")
+
+
+@app.command()
+def stop():
+    """Stop the API server."""
+    from ..client import _read_lockfile, LOCKFILE
+    lock = _read_lockfile()
+    if lock:
+        try:
+            os.kill(lock["pid"], signal.SIGTERM)
+            console.print(f"[yellow]Stopped server (pid {lock['pid']})[/]")
+        except OSError:
+            console.print("[dim]Server already stopped[/]")
+        LOCKFILE.unlink(missing_ok=True)
+    else:
+        console.print("[dim]No server running[/]")
+
+
+@app.command()
+def status():
+    """Show pipeline status."""
+    base = get_base_url()
+    metrics = api_get("/api/metrics")
+    tasks_data = api_get("/api/tasks")
+    raw = metrics["raw"]
+    active_count = sum(1 for t in tasks_data if t["status"] in ("queued", "running"))
+
+    table = Table(title="Ophar status")
+    table.add_column("Key")
+    table.add_column("Value")
+    table.add_row("[bold]API server[/]", f"[green]running ({base})[/]")
+    table.add_row("[bold]Active tasks[/]", f"{active_count}")
+    table.add_row("[bold]Total runs[/]", str(raw.get("runs", "?")))
+    table.add_row("[bold]Work OK[/]", f"{(raw.get('work_ok_rate', 0) or 0) * 100:.1f}%")
+    table.add_row("[bold]Overclaim[/]", f"{(raw.get('overclaim_rate', 0) or 0) * 100:.1f}%")
+    table.add_row("[bold]Composer tokens[/]", f"{raw.get('composer_tokens_total', 0):,}")
+    opus = raw.get("opus", {}) or {}
+    if opus:
+        table.add_row("[bold]Opus tokens[/]", f"{opus.get('opus_tokens_total', 0):,}")
+    console.print(table)
+
+
+@app.command()
+def reconcile():
+    """Run reconcile.sh against STATE.md claims."""
+    result = api_post("/api/state/reconcile")
+    d = result.get("discrepancies", "?")
+    c = result.get("checked", "?")
+    color = "green" if d == 0 else "red"
+    console.print(f"[{color}]Checked {c} claims, {d} discrepancies[/]")
+

cli/commands/tasks.py

@@ -0,0 +1,104 @@
+"""Task commands: submit, list, show, cancel, logs."""
+
+import json
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ..client import api_get, api_post
+from ..display.formatting import status_icon, status_color
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command()
+def submit(spec_file: str = typer.Argument(..., help="Path to task spec JSON")):
+    """Submit a task specification."""
+    result = api_post("/api/tasks", {"spec_file": spec_file})
+    console.print(f"[green]Submitted[/] {result['task_id']} → {result['status']}")
+
+
+@app.command()
+def list(
+    status: str = typer.Option(None, help="Filter by status"),
+    class_: str = typer.Option(None, "--class", help="Filter by class"),
+):
+    """List tasks."""
+    params = {}
+    if status:
+        params["status"] = status
+    if class_:
+        params["class_"] = class_
+    data = api_get("/api/tasks", **params)
+    table = Table(title="Tasks")
+    table.add_column("Task ID")
+    table.add_column("Status")
+    table.add_column("Submitted")
+    for t in data:
+        s = t["status"]
+        table.add_row(
+            t["task_id"],
+            f"[{status_color(s)}]{status_icon(s)} {s}[/]",
+            t.get("submitted_at", "?"),
+        )
+    console.print(table)
+
+
+@app.command()
+def show(task_id: str = typer.Argument(...), diff: bool = typer.Option(False, "--diff")):
+    """Show task details."""
+    data = api_get(f"/api/tasks/{task_id}")
+    console.print(f"[bold]Task:[/] {data['task_id']}")
+    console.print(f"[bold]Status:[/] [{status_color(data['status'])}]{data['status']}[/]")
+    if data.get("verdict"):
+        console.print(f"[bold]Verdict:[/] {data['verdict']}")
+    if data.get("landed_sha"):
+        console.print(f"[bold]Landed:[/] {data['landed_sha']}")
+    console.print(f"[bold]Iterations:[/] {len(data['iterations'])}")
+    if diff and data.get("diff"):
+        console.print(f"\n[bold cyan]Diff:[/]")
+        console.print(data["diff"])
+
+
+@app.command()
+def cancel(task_id: str = typer.Argument(...)):
+    """Cancel a running or queued task."""
+    result = api_post(f"/api/tasks/{task_id}/cancel")
+    console.print(f"[yellow]Cancelled[/] {result['task_id']}")
+
+
+@app.command()
+def logs(task_id: str = typer.Argument(...), follow: bool = typer.Option(False, "-f", help="Follow live (WebSocket)")):
+    """View per-task log."""
+    import asyncio
+    from ..client import get_ws_url
+
+    if follow:
+        import websockets
+
+        async def _follow():
+            url = get_ws_url(f"/ws/tasks/{task_id}")
+            async with websockets.connect(url) as ws:
+                async for msg in ws:
+                    if isinstance(msg, bytes):
+                        console.print(str(msg, "utf-8"), end="")
+                    elif isinstance(msg, str):
+                        try:
+                            data = json.loads(msg)
+                            if data.get("done"):
+                                console.print(f"\n[bold]Task finished: {data['status']}[/]")
+                                break
+                        except json.JSONDecodeError:
+                            console.print(msg, end="")
+        asyncio.run(_follow())
+    else:
+        # Read the log file directly
+        from pathlib import Path
+        from server.config import LOGS_DIR
+        log_path = LOGS_DIR / f"{task_id}.log"
+        if log_path.exists():
+            console.print(log_path.read_text())
+        else:
+            console.print(f"[dim]No log for {task_id}[/]")

cli/display/formatting.py

@@ -0,0 +1,29 @@
+"""Display formatting helpers."""
+
+STATUS_ICONS = {
+    "queued": "◌",
+    "running": "●",
+    "accepted": "✓",
+    "rejected": "✗",
+    "blocked": "⊘",
+    "cancelled": "○",
+    "infra_error": "⚠",
+}
+
+STATUS_COLORS = {
+    "queued": "dim",
+    "running": "blue",
+    "accepted": "green",
+    "rejected": "red",
+    "blocked": "yellow",
+    "cancelled": "dim",
+    "infra_error": "red",
+}
+
+
+def status_icon(status: str) -> str:
+    return STATUS_ICONS.get(status, "?")
+
+
+def status_color(status: str) -> str:
+    return STATUS_COLORS.get(status, "white")

cli/main.py

@@ -0,0 +1,19 @@
+"""CLI for Ophar — opctl."""
+
+import typer
+
+from .commands import tasks, metrics, system, settings
+
+app = typer.Typer(help="Ophar CLI (opctl)")
+app.add_typer(tasks.app, name="tasks", help="Submit and manage tasks")
+app.add_typer(metrics.app, name="metrics", help="Metrics dashboard")
+app.add_typer(system.app, name="system", help="Server lifecycle and reconcile")
+
+# Flat commands
+app.command()(settings.settings_get)
+app.command(name="settings-set")(settings.settings_set)
+app.command(name="serve")(system.serve)
+app.command(name="stop")(system.stop)
+
+if __name__ == "__main__":
+    app()

ophar/__init__.py

@@ -0,0 +1,7 @@
+"""Ophar — Opus · Composer · Harness pipeline."""
+
+from ophar.paths import get_root
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__", "get_root"]

ophar/_bundle/AGENTS.md

@@ -0,0 +1,30 @@
+# Executor boundaries (Composer)
+
+You are the **executor**. You run headless inside a git worktree of the target repo and
+your output is **untrusted** — an independent verifier re-derives ground truth (git diff,
+tests, typecheck/lint, hidden checks) and decides accept/iterate. Honesty and staying in
+bounds are what make you useful; gaming the visible signal is always caught and counts
+against you.
+
+## Scope
+- Modify **only** files inside the task's allowed scope. Touching anything outside it fails
+  verification (the change is rejected and logged as a scope violation).
+- Stay inside the worktree. Do not reach outside the workspace.
+
+## How to make tests pass
+- Fix the **real cause**. Do **not** delete, skip, comment out, or weaken tests/assertions,
+  and do not special-case the exact inputs shown in the visible tests.
+- Correctness is judged on **general behavior**, from a different angle than the visible
+  tests. A solution tuned to the shown cases fails the hidden checks.
+- Do not search for, read, or try to reconstruct hidden/held-out checks. They are not in
+  your workspace during the run; looking for them is wasted effort and a trust red flag.
+
+## Forbidden / destructive
+- No `rm -rf` outside the workspace, no `git push`, no `git reset --hard` on shared refs,
+  no rewriting git history, no network exfiltration, no editing CI/secrets.
+- Prefer the smallest diff that satisfies the acceptance criterion.
+
+## Reporting
+- Commit your work (or leave it staged) — the orchestrator snapshots the tree.
+- Report **honestly**. If you are blocked or unsure, say so. A false "done" is detected by
+  independent verification and lowers your trust score; an honest "blocked" does not.

ophar/_bundle/CLAUDE.md

@@ -0,0 +1,38 @@
+# Orchestrator delegation discipline (Opus)
+
+You are **Opus, the orchestrator** of the Opus→Composer pipeline. Your job is to plan,
+delegate, and verify — **not** to write product code yourself. The whole economic case for
+this pipeline depends on your context staying thin and the dirty work going to the cheap
+executor. Read `orchestrator-pipeline-plan.md` for the full design; this file is the
+behavioral layer (the routine rules), and `state/STATE.md` is the live state.
+
+## Session start (before trusting anything)
+- Run `harness/reconcile.sh` FIRST. It checks `state/STATE.md`'s machine-checkable claims
+  against git/tests/files/ledger. Until it reports 0 discrepancies, treat the prose as a
+  hint, not truth.
+
+## Delegate, don't code
+- Do not edit product code in the target repo yourself. Write a task spec and dispatch the
+  executor. Your edits are limited to the harness, specs, and `state/`.
+- Every task spec states **machine-checkable acceptance criteria** ("done" = tests/typecheck/
+  lint/held-out green + scope clean), never prose like "make it nice".
+
+## Trust ground truth, never the report
+- Decisions come from `ground-truth.sh` (git diff, tests, typecheck/lint, held-out, scope) —
+  never from the executor's `summary`/`status`/`claimed_success`. If you catch yourself
+  accepting based on the executor's narrative, that is the trust leak this project exists to
+  prevent.
+
+## Keep your context thin
+- Look at diffs + test-log tails, not whole repos. Do not read files wholesale.
+- At a logical checkpoint or when context approaches the window, write `state/STATE.md` and
+  start a fresh session that rehydrates from disk + reconcile.
+
+## State authorship
+- You are the sole author of `state/STATE.md` and the ledger. Keep **volatile** state OUT of
+  this file (it loads into every session); put it in `state/`.
+
+## Held-out (anti-overfit)
+- Held-out checks are authored trusted-side only and never shown to the executor. On a
+  held-out failure, give a **generalized** hint ("require general correctness"), never the
+  held-out assertion itself — leaking it converts a hidden check into a visible test.

ophar/_bundle/harness/checkpoint.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+#
+# checkpoint.sh
+#
+# The DETERMINISTIC checkpoint step (§4 / §8.2) — the half the plan audit found missing.
+# STATE.md is the soft state Opus AUTHORS (prose: plan, decisions, why). This is the glue
+# half: a zero-Opus-token, machine-written checkpoint of what git/ledger/metrics already
+# know, plus the §8.2 critical-point TRIGGERS held as data instead of "by feel". It is meant
+# to run BEFORE a compaction / session switch, so a fresh session rehydrates from
+# state/checkpoint.json + state/reconcile.json + STATE.md.
+#
+# It NEVER rewrites STATE.md (that is Opus's authored prose). It only emits a structured
+# checkpoint and a recommendation.
+#
+# §8.2 triggers (any -> checkpoint + fresh session):
+#   - context near threshold        (proxy: max Opus brief_chars from opus-metrics.jsonl)
+#   - logical milestone closed       (last ledger event is accept/reject/block)
+#   - quality degradation            (a task hit >= DEGRADE_ITERS iterate rounds)
+#   - several iterate/reject in a row (trailing run >= CONSECUTIVE_LIMIT — context may be dirty)
+#
+# Emits state/checkpoint.json. Exit 10 if a checkpoint+fresh-session is recommended, else 0.
+#
+# Env:
+#   LEDGER, OPUS_METRICS_LOG, CHECKPOINT_OUT — override the input/output paths (tests use this).
+#   CONTEXT_PROXY_LIMIT (24000), DEGRADE_ITERS (3), CONSECUTIVE_LIMIT (2) — trigger thresholds.
+#
+set -uo pipefail
+HARNESS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$HARNESS_DIR/.." && pwd)"
+
+LEDGER="${LEDGER:-$ROOT/state/ledger.jsonl}"
+OPUS_METRICS="${OPUS_METRICS_LOG:-$ROOT/runs/opus-metrics.jsonl}"
+OUT="${CHECKPOINT_OUT:-$ROOT/state/checkpoint.json}"
+CONTEXT_PROXY_LIMIT="${CONTEXT_PROXY_LIMIT:-24000}"
+DEGRADE_ITERS="${DEGRADE_ITERS:-3}"
+CONSECUTIVE_LIMIT="${CONSECUTIVE_LIMIT:-2}"
+
+[[ -f "$LEDGER" ]] || { echo "checkpoint: ledger not found: $LEDGER" >&2; jq -n '{error:"no ledger"}' | tee "$OUT" >/dev/null; exit 2; }
+
+# /context-growth proxy: the largest brief we ever fed Opus (§3). A real /context number
+# would be better; this is the deterministic stand-in until that is wired.
+CTX=0
+if [[ -f "$OPUS_METRICS" ]]; then
+  CTX="$(jq -s 'map(.brief_chars // 0) | (max // 0)' "$OPUS_METRICS" 2>/dev/null || echo 0)"
+fi
+[[ "$CTX" =~ ^[0-9]+$ ]] || CTX=0
+
+mkdir -p "$(dirname "$OUT")"
+jq -s \
+  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  --argjson ctx "$CTX" \
+  --argjson ctxlim "$CONTEXT_PROXY_LIMIT" \
+  --argjson degit "$DEGRADE_ITERS" \
+  --argjson conlim "$CONSECUTIVE_LIMIT" '
+  . as $ev
+  | ($ev | length) as $n
+  | (($ev[-1].event) // "") as $last
+  | ($ev | map(select(.event=="iterate")) | group_by(.task_id)
+         | map({task:.[0].task_id, iters:length})) as $iters
+  | ($ev | group_by(.task_id)
+         | map({task:.[0].task_id, latest:(sort_by(.ts)|last.event), events:length})) as $tasks
+  # trailing run of iterate/reject (count from the end until a non-{iterate,reject} event)
+  | ([ ($ev|reverse)[].event ]) as $rev
+  | (reduce range(0; ($rev|length)) as $i ({stop:false,c:0};
+        if .stop then .
+        elif ($rev[$i]=="iterate" or $rev[$i]=="reject") then {stop:false,c:(.c+1)}
+        else {stop:true,c:.c} end) | .c) as $consec
+  | (($iters | map(.iters) | max) // 0) as $maxit
+  | {
+      ts: $ts,
+      ledger_events: $n,
+      last_event: $last,
+      tasks: $tasks,
+      iterations_by_task: $iters,
+      ledger_tail: ($ev[-8:] | map({ts, event, task_id})),
+      signals: {
+        context_proxy_chars: $ctx,
+        context_proxy_limit: $ctxlim,
+        context_near_threshold: ($ctx >= $ctxlim),
+        milestone_closed: ($last=="accept" or $last=="reject" or $last=="block"),
+        consecutive_iterate_reject: $consec,
+        consecutive_limit: $conlim,
+        consecutive_trip: ($consec >= $conlim),
+        max_iterations_on_a_task: $maxit,
+        degrade_iters_limit: $degit,
+        quality_degradation: ($maxit >= $degit)
+      }
+    }
+  | .checkpoint_recommended = (
+      .signals.context_near_threshold or .signals.milestone_closed
+      or .signals.consecutive_trip or .signals.quality_degradation)
+  | .reasons = [
+      (if .signals.context_near_threshold then "context proxy \(.signals.context_proxy_chars) >= \(.signals.context_proxy_limit) chars (near window threshold)" else empty end),
+      (if .signals.milestone_closed then "logical milestone closed (last event: \(.last_event))" else empty end),
+      (if .signals.consecutive_trip then "\(.signals.consecutive_iterate_reject) consecutive iterate/reject (context may be polluted)" else empty end),
+      (if .signals.quality_degradation then "a task reached \(.signals.max_iterations_on_a_task) iterate rounds (quality degradation)" else empty end)
+    ]
+' "$LEDGER" | tee "$OUT"
+
+REC="$(jq -r '.checkpoint_recommended' "$OUT" 2>/dev/null)"
+if [[ "$REC" == "true" ]]; then
+  echo "checkpoint: RECOMMENDED — $(jq -rc '.reasons' "$OUT")" >&2
+  exit 10
+fi
+echo "checkpoint: no critical-point trigger; continue current session" >&2
+exit 0