@murk-security/runner-linux-arm64 0.0.0-stage → 0.7.1

package/runners/basic_harness_run.py

@@ -0,0 +1,1276 @@
+#!/usr/bin/env python3
+"""Blackglass product runner adapter for basic-harness (teams+directions).
+
+In-product sibling of the multiagent runner's adapter. The control-plane's
+RunnerSupervisor spawns this as:
+
+    python3 $BASIC_HARNESS_ROOT/runners/basic_harness_run.py \
+        --spec <session>/input-spec.json --session-dir <session> --events stdout
+
+It reads the RunSpec, runs the basic-harness Go binary against the target through
+prod_env.py (READ-ONLY; identities from BLACKGLASS_SECRETS_JSON), and emits Blackglass
+events on stdout: lifecycle events (run.started/completed/failed) on the main thread,
+plus a LIVE activity stream tailed from the harness's own event log. Like the
+multiagent adapter -- which follows `cmd/run-events` -- we map core events to v2 public
+events; basic-harness has no run-events subcommand, so a follower thread tails the
+harness state DB's `events` table (and newly-confirmed findings in `nodes`) directly
+and emits mapped events with periodic heartbeats so the dashboard timeline stays live.
+
+No Go-core change: the harness is driven entirely through its existing flags. Exit
+codes mirror the core runner contract: 0 ok, 2 invalid input, 3 policy refusal,
+4 cancelled.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import hashlib
+import json
+import os
+import re
+import signal
+import sqlite3
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from pathlib import Path
+from urllib.parse import urlparse
+
+ROOT = Path(os.environ.get("BASIC_HARNESS_ROOT", Path(__file__).resolve().parent.parent))
+HARNESS = os.environ.get("BASIC_HARNESS_BIN", str(ROOT / "bin" / "harness"))
+PROD_ENV = str(Path(__file__).resolve().parent / "prod_env.py")
+PROFILE_PY = os.environ.get("PROFILE_PY", str(Path(__file__).resolve().parent / "profile.py"))
+KEY_FILE = os.environ.get("BASIC_HARNESS_KEY_FILE", str(Path.home() / "Code" / "keys" / ".env"))
+
+DEFAULT_MODEL = os.environ.get("BASIC_HARNESS_MODEL", "z-ai/glm-5.3-flash")
+# Premium models sit at two roles; everything else runs on the flash base model:
+#  - COORDINATOR (kimi-k3): the per-team synthesis locus that authors every finding. The
+#    Juice Shop sweep (2026-10-28) showed K3 here wins on recall + category coverage, while
+#    the SAME model at the orchestrator made recall worse and was unstable (a full-length
+#    run that scored 0). This is where the expensive reasoning earns its keep.
+#  - ORCHESTRATOR (glm-5.3): the council chair + members that prioritize directions across a
+#    large surface. Kept premium (but NOT k3) on purpose: the sweep ran single-planner
+#    (baseline) orchestration on one mid-size target, which under-weights the orchestrator's
+#    real value on big multi-host targets where council planning over a capable model pays
+#    off. In council mode all 3 members and the chair run on this model (orchestrator.go).
+DEFAULT_COORD_MODEL = os.environ.get("BASIC_HARNESS_COORD_MODEL", "moonshotai/kimi-k3")
+DEFAULT_ORCH_MODEL = os.environ.get("BASIC_HARNESS_ORCH_MODEL", "z-ai/glm-5.3")
+DEFAULT_ORCHESTRATOR = os.environ.get("BASIC_HARNESS_ORCHESTRATOR", "council")
+
+# Remediation (patch generation) runs a small best-of-N + reviewer pipeline, NOT the flash
+# base model: a patch is one cheap job (not a 45-min scan), so premium models earn their keep
+# on correctness. Generator = glm-5.3 (full, stronger than flash); reviewer = kimi-k3 (the
+# strongest reasoner, used to judge "does this actually fix it, minimally, no regression").
+# These literals ship in the hosted path (BASIC_HARNESS_* env is not forwarded to the runner).
+DEFAULT_REMEDIATE_MODEL = os.environ.get("BASIC_HARNESS_REMEDIATE_MODEL", DEFAULT_ORCH_MODEL)
+DEFAULT_REMEDIATE_REVIEWER = os.environ.get("BASIC_HARNESS_REMEDIATE_REVIEWER", DEFAULT_COORD_MODEL)
+try:
+    DEFAULT_REMEDIATE_CANDIDATES = max(1, int(os.environ.get("BASIC_HARNESS_REMEDIATE_CANDIDATES", "3")))
+except ValueError:
+    DEFAULT_REMEDIATE_CANDIDATES = 3
+
+# Two scan profiles, selected by RunSpec.scanProfile (default 'full'). PR = fast, cheap,
+# diff-scoped gate that must return in minutes so it can block a PR; FULL = the deep
+# whole-repo audit. The control plane curates the child env, so these LITERALS (not the
+# BASIC_HARNESS_* env, which only reaches local dev) are what ship in the hosted path.
+# Each profile sets the model placement, whether the council runs, breadth, and the cost
+# backstop; the time cap comes from policy.maxDurationMinutes, falling back to the
+# profile's default_minutes. See [[murk-pricing-launch-plan]].
+SCAN_PROFILES: dict[str, dict] = {
+    "pr": {
+        "orchestrator": "baseline",   # no council: keep the PR gate fast and cheap
+        "coord_model": "",            # flash everywhere incl. the coordinator
+        "orch_model": "",
+        "teams": "3", "cells": "2", "team_calls": "40", "workers": "6",
+        "max_cost": "3", "default_minutes": 10.0,
+    },
+    "full": {
+        "orchestrator": DEFAULT_ORCHESTRATOR,  # council
+        "coord_model": DEFAULT_COORD_MODEL,    # kimi-k3 at the synthesis locus
+        "orch_model": DEFAULT_ORCH_MODEL,      # glm-5.3 council chair + members
+        "teams": "5", "cells": "3", "team_calls": "60", "workers": "8",
+        "max_cost": "15", "default_minutes": 45.0,
+    },
+}
+
+
+def scan_profile_for(spec: dict) -> tuple[str, dict]:
+    """Resolve (name, config) for a RunSpec's scanProfile. Unknown/absent -> 'full'
+    (the pre-two-profile default), so existing assessments keep their behavior."""
+    name = str((spec or {}).get("scanProfile") or "full").lower()
+    if name not in SCAN_PROFILES:
+        name = "full"
+    return name, SCAN_PROFILES[name]
+
+
+def _pr_changed_files(checkout: str, base: str, limit: int = 100) -> list[str]:
+    """Files changed between `base` and HEAD in the checkout (name-only). Safe: returns
+    [] on any git error, so a scoping failure degrades to a whole-repo PR scan rather
+    than breaking the run."""
+    try:
+        out = subprocess.run(
+            ["git", "-C", checkout, "diff", "--name-only", f"{base}...HEAD"],
+            capture_output=True, text=True, timeout=30, check=False,
+        )
+        files = [ln.strip() for ln in out.stdout.splitlines() if ln.strip()]
+        return files[:limit]
+    except (OSError, subprocess.SubprocessError):
+        return []
+
+
+def _pr_scope_text(files: list[str]) -> str:
+    """Brief addendum that focuses a PR scan on the changed files + their blast radius."""
+    listing = "\n".join(f"- {f}" for f in files)
+    return (
+        "\n\n## PR scope (focus here)\n"
+        "This is a fast pull-request gate. Concentrate on the code CHANGED in this PR and "
+        "the code that directly calls into or is reached from it (its blast radius). Do NOT "
+        "attempt a whole-repo audit. Changed files:\n" + listing
+    )
+HEARTBEAT_S = 10.0
+
+
+class Emitter:
+    """Serialize public events onto stdout with a single monotonic sequence.
+
+    Thread-safe: the main-thread lifecycle emits and the follower-thread activity
+    emits share one counter and one lock, so lines never interleave and sequence
+    numbers stay strictly increasing.
+    """
+
+    def __init__(self, run_id: str):
+        self.run_id = run_id
+        self.seq = 0
+        self.start_ts = time.time()
+        self._lock = threading.Lock()
+
+    def emit(self, type_: str, payload: dict, source: dict | None = None) -> None:
+        with self._lock:
+            self.seq += 1
+            event = {
+                "protocolVersion": "2",
+                "eventId": uuid.uuid4().hex,
+                "runId": self.run_id,
+                "sequence": self.seq,
+                "timestamp": dt.datetime.now(dt.timezone.utc).isoformat().replace("+00:00", "Z"),
+                "type": type_,
+                "source": source or {},
+                "payload": payload,
+            }
+            sys.stdout.write(json.dumps(event) + "\n")
+            sys.stdout.flush()
+
+
+def fingerprint(title: str) -> str:
+    # Stable across runs so the control plane dedupes a recurring finding per application.
+    return "bh-" + hashlib.sha256((title or "").strip().lower().encode("utf-8")).hexdigest()[:24]
+
+
+_EVIDENCE_RE = re.compile(r"Evidence:\s*\[([0-9,\s]+)\]")
+MAX_RECIPE_OPS = 24  # bound a reproduction recipe (findings cite a handful of calls)
+
+
+def reproduction_ops(con, body: str) -> list[dict]:
+    """Rebuild a finding's replayable recipe from the evidence it cited. A confirmed
+    finding embeds its supporting evidence ids in the body as 'Evidence: [id id ...]';
+    each id is an env_log row whose `request` is the exact {op, args} that was sent.
+    We fetch those requests in id order (= the order they were run) and keep op+args,
+    so a later retest can replay precisely the calls that proved the finding. Read-only
+    and best-effort: any parse/DB hiccup yields no recipe rather than raising."""
+    m = _EVIDENCE_RE.search(body or "")
+    if not m:
+        return []
+    ids = [int(tok) for tok in re.split(r"[,\s]+", m.group(1).strip()) if tok.isdigit()]
+    if not ids:
+        return []
+    ids = ids[:MAX_RECIPE_OPS]
+    placeholders = ",".join("?" * len(ids))
+    ops: list[dict] = []
+    try:
+        for (req,) in con.execute(
+            f"SELECT request FROM env_log WHERE id IN ({placeholders}) ORDER BY id", ids
+        ).fetchall():
+            try:
+                r = json.loads(req) if req else {}
+            except (json.JSONDecodeError, TypeError):
+                continue
+            if isinstance(r, dict) and r.get("op"):
+                ops.append({"op": str(r.get("op")), "args": r.get("args") if isinstance(r.get("args"), dict) else {}})
+    except sqlite3.Error:
+        return []
+    return ops
+
+
+_CODE_RE = re.compile(r"\nCode:\s*(.+)")
+
+
+def _source_from_body(body: str) -> dict | None:
+    """Extract a structured source location {file, line} from a finding's body.
+
+    A confirmed finding's body carries its code citations on a 'Code: path:line, ...'
+    line (team.go writes refs there). The control plane stores this as finding.source
+    and both the dashboard's 'Create patch' button and the remediate flow gate on
+    source.file -- without it the button is disabled and no patch can be generated.
+    We take the FIRST ref (unix paths have no ':', so the last ':<n>' is the line;
+    'path:12-20' ranges keep the start line). Best-effort: None when absent/unparseable."""
+    m = _CODE_RE.search(body or "")
+    if not m or not m.group(1).strip():
+        return None
+    first = re.split(r"[,\s]+", m.group(1).strip())[0]
+    mm = re.match(r"^(.*):(\d+)(?:-\d+)?$", first)
+    if mm:
+        return {"file": mm.group(1), "line": int(mm.group(2))}
+    return {"file": first} if first else None
+
+
+MAX_SNIPPET = 800  # bound every evidence/code snippet (sensitive data + report size)
+_ALL_CODE_RE = re.compile(r"\nCode:\s*(.+)")
+
+
+def _clip(s: str, n: int = MAX_SNIPPET) -> str:
+    s = s or ""
+    return s if len(s) <= n else s[:n] + " …[truncated]"
+
+
+def _response_proof(resp_text: str) -> dict:
+    """A bounded, structured view of what a cited env call actually returned — the proof.
+    Read verbatim from env_log.response; never synthesized."""
+    out: dict = {}
+    try:
+        r = json.loads(resp_text) if resp_text else {}
+    except (json.JSONDecodeError, TypeError):
+        return {"snippet": _clip(str(resp_text))}
+    if isinstance(r, dict):
+        for k in ("status", "ok", "authenticated", "host", "path"):
+            if k in r:
+                out[k] = r[k]
+        body = r.get("body", r.get("text", r))
+        out["snippet"] = _clip(body if isinstance(body, str) else json.dumps(body, ensure_ascii=False))
+    else:
+        out["snippet"] = _clip(json.dumps(r, ensure_ascii=False))
+    return out
+
+
+def evidence_ops(con, body: str) -> list[dict]:
+    """The cited env calls as {evidence_id, op, args, response} — request AND the real
+    response that proved the finding. Read verbatim from env_log; best-effort, no recipe
+    on any DB/parse hiccup rather than raising or guessing."""
+    m = _EVIDENCE_RE.search(body or "")
+    if not m:
+        return []
+    ids = [int(t) for t in re.split(r"[,\s]+", m.group(1).strip()) if t.isdigit()][:MAX_RECIPE_OPS]
+    if not ids:
+        return []
+    ph = ",".join("?" * len(ids))
+    ops: list[dict] = []
+    try:
+        for eid, req, resp in con.execute(
+            f"SELECT id, request, response FROM env_log WHERE id IN ({ph}) ORDER BY id", ids
+        ).fetchall():
+            try:
+                r = json.loads(req) if req else {}
+            except (json.JSONDecodeError, TypeError):
+                continue
+            if isinstance(r, dict) and r.get("op"):
+                ops.append({
+                    "evidence_id": eid,
+                    "op": str(r.get("op")),
+                    "args": r.get("args") if isinstance(r.get("args"), dict) else {},
+                    "response": _response_proof(resp),
+                })
+    except sqlite3.Error:
+        return []
+    return ops
+
+
+def _read_code_snippet(checkout: str | None, file: str | None, line: int | None, ctx: int = 3) -> str:
+    """The actual source lines around a cited path:line, read from the checkout the harness
+    audited. Returns '' (never a guess) if the file/line is missing or escapes the checkout."""
+    if not checkout or not file:
+        return ""
+    try:
+        base = Path(checkout).resolve()
+        target = (base / file).resolve()
+        if base not in target.parents and target != base:
+            return ""  # path-traversal guard: only inside the checkout
+        if not target.is_file():
+            return ""
+        text = target.read_text(errors="replace").splitlines()
+        if line and line > 0:
+            lo, hi = max(0, line - 1 - ctx), min(len(text), line + ctx)
+            return _clip("\n".join(f"{lo + 1 + i}: {text[lo + i]}" for i in range(hi - lo)))
+        return _clip("\n".join(text[: ctx * 2]))
+    except OSError:
+        return ""
+
+
+def code_refs(body: str, checkout: str | None) -> tuple[list[dict], list[str]]:
+    """All cited code locations ('Code: a:12, b:30-40') as {file, line, snippet} plus their
+    'file:line' strings. Snippets are read from the checkout; absent when unavailable."""
+    m = _ALL_CODE_RE.search(body or "")
+    if not m or not m.group(1).strip():
+        return [], []
+    refs: list[dict] = []
+    strs: list[str] = []
+    for tok in re.split(r"[,\s]+", m.group(1).strip())[:MAX_RECIPE_OPS]:
+        mm = re.match(r"^(.*?):(\d+)(?:-\d+)?$", tok)
+        if mm:
+            ref = {"file": mm.group(1), "line": int(mm.group(2))}
+        elif tok:
+            ref = {"file": tok}
+        else:
+            continue
+        strs.append(tok)
+        snip = _read_code_snippet(checkout, ref.get("file"), ref.get("line"))
+        if snip:
+            ref["snippet"] = snip
+        refs.append(ref)
+    return refs, strs
+
+
+def parse_meta(raw: str | None) -> dict:
+    """A finding node's `meta` is a JSON object of the model-authored assessment
+    (severity, category, cwe, impact, remediation) that team.go writes for a
+    confirmed finding. Best-effort: a bad/absent value yields {}."""
+    if not raw:
+        return {}
+    try:
+        m = json.loads(raw)
+        return m if isinstance(m, dict) else {}
+    except (json.JSONDecodeError, TypeError):
+        return {}
+
+
+# HTTP-family ops that name a request (path/method/host, like the `http` op's args).
+_REQUEST_OPS = ("http", "login", "render", "oob")
+
+
+def _request_url(origin: str, host: str | None, path: str) -> str:
+    """Absolute URL for a cited request. A recon-pivoted request carries its own `host`
+    (a subdomain), which takes precedence over the primary origin's host."""
+    if host:
+        scheme = (urlparse(origin).scheme or "https") if origin else "https"
+        sep = "" if path.startswith("/") else "/"
+        return f"{scheme}://{host}{sep}{path}"
+    if origin and path.startswith("/"):
+        return origin.rstrip("/") + path
+    return path
+
+
+def endpoint_and_steps(ops: list[dict] | None, origin: str) -> tuple[dict | None, list[str]]:
+    """Derive the affected endpoint and human reproduction steps from the cited env ops.
+    Deterministic and evidence-derived (not guessed): the endpoint is the last concrete
+    request that names a path -- the call that demonstrates the issue. Honours a
+    recon-pivoted `host`, treats `login` as POST, and expands a `diff` op's sub-requests."""
+    steps: list[str] = []
+    endpoint: dict | None = None
+
+    def _request(name: str, args: dict) -> None:
+        nonlocal endpoint
+        path = args.get("path") if isinstance(args.get("path"), str) else None
+        host = args.get("host") if isinstance(args.get("host"), str) else None
+        who = args.get("identity") or args.get("as")
+        if path:
+            method = str(args.get("method") or ("POST" if name == "login" else "GET")).upper()
+            label = (host + path) if host else path
+            step = f"{method} {label}" + (f" (as {who})" if who else "")
+            steps.append(step)
+            endpoint = {"method": method, "path": path, "url": _request_url(origin, host, path)}
+        elif name == "login" and who:
+            steps.append(f"Sign in as {who}")
+        else:
+            subject = args.get("subject") or who or ""
+            steps.append(f"{name} {subject}".strip())
+
+    for op in ops or []:
+        name = str(op.get("op") or "")
+        if not name:
+            continue
+        args = op.get("args") if isinstance(op.get("args"), dict) else {}
+        if name == "diff" and isinstance(args.get("requests"), list):
+            for sub in args["requests"]:  # a differential oracle runs 2+ http-shaped requests
+                if isinstance(sub, dict):
+                    _request("http", sub)
+        elif name in _REQUEST_OPS:
+            _request(name, args)
+        else:
+            subject = args.get("subject") or args.get("identity") or args.get("as") or ""
+            steps.append(f"{name} {subject}".strip())
+    return endpoint, steps
+
+
+def finding_payload(title: str, body: str, ops: list[dict] | None = None,
+                    fingerprint_override: str | None = None, verification: str | None = None,
+                    meta: dict | None = None, origin: str = "",
+                    con=None, checkout: str | None = None) -> dict:
+    title = (title or "Untitled finding").strip()
+    body = (body or "").strip()
+    meta = meta or {}
+    # With a DB connection, build the concrete, verbatim proof the finding cited: each env
+    # call's request AND response, and every code reference (with a snippet from the audited
+    # checkout). All read from the run's own records -- nothing is generated. Without a
+    # connection (unit tests / callers that pass ops directly), fall back to the given ops.
+    code_ref_list: list[dict] = []
+    ref_strings: list[str] = []
+    if con is not None:
+        ops = evidence_ops(con, body)
+        code_ref_list, ref_strings = code_refs(body, checkout)
+    payload = {
+        # On a retest we re-emit under the ORIGINAL finding's fingerprint so the control
+        # plane reconciles identity (fingerprint = sha256(title), but the retest title may
+        # paraphrase, so the adapter passes the matched original's fingerprint explicitly).
+        "fingerprint": fingerprint_override or fingerprint(title),
+        "title": title[:300],
+        "verification": verification or "unverified",  # 'reproduced' when re-confirmed on a retest
+        "confidence": "high",          # emitted only for harness-confirmed findings
+        "description": body[:4000],
+        "evidence": body[:2000],
+    }
+    # The assessment the model authored for this finding (team.go gates a confirmed
+    # finding on it). Each field is passed through only when present -- never defaulted
+    # to a guessed severity/category, so an unrated finding stays honestly unrated.
+    for key in ("severity", "category", "cwe", "impact", "remediation"):
+        val = meta.get(key)
+        if isinstance(val, str) and val.strip():
+            payload[key] = val.strip()
+    endpoint, steps = endpoint_and_steps(ops, origin)
+    if endpoint:
+        payload["endpoint"] = endpoint
+    if steps:
+        payload["steps"] = steps[:MAX_RECIPE_OPS]
+    if ops or code_ref_list:
+        # The replayable recipe + proof: the cited env ops (request + the real response
+        # each returned) and the cited code locations with snippets. A retest replays the
+        # ops; the report/chat/MCP surface the responses + code as concrete evidence.
+        repro: dict = {}
+        if ops:
+            repro["ops"] = ops
+        if code_ref_list:
+            repro["codeRefs"] = code_ref_list
+        payload["reproduction"] = repro
+    if ref_strings:
+        payload["evidenceRefs"] = ref_strings
+    src = _source_from_body(body)
+    if src and src.get("file"):
+        # Structured source location (file[:line]) parsed from the finding's code
+        # citations, so the dashboard can offer 'Create patch' and the remediate flow
+        # knows which file to read. Absent when the finding cited no path:line.
+        payload["source"] = src
+    return payload
+
+
+def sign_in_test_accounts(spec: dict, em: "Emitter") -> dict:
+    """Sign every username-and-password test account in, and report each outcome as an
+    identity.authenticated event (the dashboard shows whether the account works). Returns
+    {identity id: {cookie, headers} | {error}} for the agents' environment processes
+    (prod_env.load_shared_sessions). Credentials never leave prod_env."""
+    import prod_env  # sibling module; imported here so other run kinds don't load it
+
+    try:
+        target = prod_env.Target(spec, prod_env.load_secrets())
+    except SystemExit:  # no origin to sign in to
+        return {}
+    shared: dict[str, dict] = {}
+    for iid, ident in target.identities.items():
+        if not prod_env.is_password_account(ident):
+            continue
+        result = prod_env.sign_in(target, iid)
+        ok = bool(result.get("authenticated"))
+        em.emit("identity.authenticated", {
+            "identityId": iid,
+            "ok": ok,
+            "status": result.get("status"),
+            "detail": str(result.get("note") or result.get("error") or "")[:500],
+        })
+        shared[iid] = ({"cookie": target.sessions.get(iid, ""), "headers": target.session_headers.get(iid, {})}
+                       if ok else {"error": str(result.get("error") or "the sign-in failed")})
+    return shared
+
+
+def run_prescan(spec_path: str, session: Path, tier: str) -> dict | None:
+    """Deterministic posture pre-pass over the target's public surface (security
+    headers, cookie flags, TLS, exposed paths, version->CVE) via profile.py. The
+    output profile.json is consumed by prod_env.py to STEER the agents toward the
+    signals it found (BLACKGLASS_PROFILE), and returned here to carry the coverage +
+    posture observations into the report. Best-effort: any failure or timeout disables
+    it without blocking the scan, and it never emits findings itself (signals, not
+    verdicts -- the agents confirm and the model assesses anything that is a real
+    vulnerability, so nothing is reported on a hardcoded heuristic)."""
+    out = session / "profile.json"
+    try:
+        subprocess.run(
+            [sys.executable, PROFILE_PY, "--spec", spec_path, "--out", str(out), "--tier", tier],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=120, check=False,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return None
+    if not out.exists():
+        return None
+    try:
+        data = json.loads(out.read_text())
+        return data if isinstance(data, dict) else None
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def write_report(session: Path, run_id: str, spec: dict, origin: str, scan_name: str,
+                 report_model: str, recs: list, prescan: dict | None, started_ts: float) -> None:
+    """Assemble the customer report and write it to the session dir as report.md, which
+    the control plane serves at GET /api/runs/:id/report. Deterministic sections plus an
+    isolated LLM-authored executive summary (best-effort). Never raises: a report problem
+    must not fail the scan."""
+    try:
+        import report as _report
+        try:
+            import remediate as _rem  # reused: isolated OpenRouter chat + key loader
+        except Exception:  # noqa: BLE001
+            _rem = None
+        views = [payload for _fid, _title, payload in recs]
+        idents = [str(i.get("id") or i.get("kind")) for i in (spec.get("identities") or [])
+                  if isinstance(i, dict) and (i.get("id") or i.get("kind"))]
+        run_meta = {
+            "target": origin or (spec.get("target") or {}).get("name") or "the target application",
+            "scanProfile": scan_name,
+            "runId": run_id,
+            "hosts": (spec.get("scope") or {}).get("allowedHosts") or [],
+            "actionTier": (spec.get("policy") or {}).get("actionTier") or "passive (read-only)",
+            "identities": idents,
+            "startedAt": time.strftime("%Y-%m-%d", time.gmtime(started_ts)),
+            "durationMin": max(0.0, (time.time() - started_ts) / 60.0),
+        }
+        key = os.environ.get("OPENROUTER_API_KEY") or ""
+        if not key and _rem is not None and os.path.exists(KEY_FILE):
+            try:
+                key = _rem.load_key(KEY_FILE)
+            except Exception:  # noqa: BLE001
+                key = ""
+        call = _rem.call_model if _rem is not None else None
+        # LLM-authored executive summary: try the configured report model, then fall back
+        # to the base model (proven via the gateway) before the deterministic summary.
+        # Failures are logged to stderr (harness.log) so a silent fallback is diagnosable.
+        log = lambda msg: sys.stderr.write(f"[report] {msg}\n")  # noqa: E731
+        narrative = None
+        for m in dict.fromkeys([report_model, DEFAULT_MODEL]):  # ordered, de-duplicated
+            if not m:
+                continue
+            narrative = _report.llm_summary(views, prescan, run_meta, key or None, m, call=call, log=log)
+            if narrative:
+                break
+        if not narrative:
+            narrative = _report._fallback_summary(views, prescan)
+        (session / "report.md").write_text(
+            _report.build_report(run_meta=run_meta, findings=views, prescan=prescan, narrative=narrative))
+    except Exception as exc:  # noqa: BLE001 — report generation is best-effort
+        sys.stderr.write(f"report generation skipped: {exc}\n")
+
+
+def map_event(kind: str, agent: str, data: dict):
+    """Map one harness `events` row to a Blackglass v2 public-event (type, payload, source).
+
+    Emits only flat, allowlisted keys (sanitizePublicEvent projects to the per-type
+    allowlist). Noisy/internal kinds (agent.msg, llm.*, node.add, board.*, tool.output)
+    are dropped to keep the timeline legible.
+    """
+    src = {"agentId": agent} if agent else {}
+    if kind == "agent.start":
+        return "agent.started", {
+            "id": agent, "agentType": data.get("role"), "status": "running",
+            "model": data.get("model"), "requestedModel": data.get("model"),
+        }, src
+    if kind == "agent.end":
+        return "agent.completed", {
+            "id": agent, "agentType": data.get("role"), "status": "completed",
+            "summary": str(data.get("reason") or data.get("finish") or ""),
+        }, src
+    if kind == "tool.start":
+        return "activity.recorded", {"tool": data.get("name"), "outcome": "started", "callId": data.get("call")}, src
+    if kind == "tool.end":
+        return "activity.recorded", {
+            "tool": data.get("name"), "outcome": "ok",
+            "callId": data.get("call"), "durationMs": data.get("ms"),
+        }, src
+    if kind == "env.call":
+        # data = {id, request:{op,args}, response:{...}}. A `login` against a NAMED test
+        # identity becomes a first-class sign-in-outcome event so the control plane can
+        # record whether that credential actually worked (the only auth that matters is
+        # the one exercised in the real scan context).
+        req = data.get("request") if isinstance(data.get("request"), dict) else {}
+        resp = data.get("response") if isinstance(data.get("response"), dict) else {}
+        op = str((req.get("op") if isinstance(req, dict) else None) or "request")
+        if op == "login":
+            iargs = req.get("args") if isinstance(req.get("args"), dict) else {}
+            identity = iargs.get("identity") or iargs.get("as")
+            if identity:
+                return "identity.authenticated", {
+                    "identityId": str(identity),
+                    "ok": bool(resp.get("authenticated")),
+                    "status": resp.get("status"),
+                    "detail": str(resp.get("note") or resp.get("error") or "")[:500],
+                }, src
+        return "activity.recorded", {"tool": "http", "outcome": "ok", "summary": op}, src
+    if kind in ("round.phase", "round.start", "round.gather", "round.digest", "cell.start"):
+        return "phase.changed", {"phase": str(data.get("phase") or kind.split(".")[-1])}, None
+    return None
+
+
+class Follower(threading.Thread):
+    """Tail the harness state DB live: map `events` rows to activity events and stream
+    newly-confirmed findings, emitting heartbeats so the dashboard timer advances."""
+
+    def __init__(self, db: str, em: Emitter, emitted_findings: set[int], emit_findings: bool = True,
+                 origin: str = "", checkout: str | None = None):
+        super().__init__(daemon=True)
+        self.db = db
+        self.em = em
+        self.emitted = emitted_findings
+        self.origin = origin  # for deriving each finding's endpoint URL from its cited ops
+        self.checkout = checkout  # source tree, for reading cited code snippets into findings
+        # A retest run suppresses live finding emission: findings are matched back to the
+        # originals and re-emitted (with the original fingerprint) in the final reconcile.
+        self.emit_findings = emit_findings
+        self._stopped = threading.Event()  # NB: not `_stop` -- that shadows Thread._stop
+
+    def stop(self) -> None:
+        self._stopped.set()
+
+    def _connect(self):
+        # Open with mode=rw (uri), NOT a plain connect: a plain connect would CREATE the
+        # db file, and the harness refuses to start if its -db path already exists -- so
+        # the follower must never create it. mode=rw also reads WAL correctly (mode=ro
+        # cannot, as it can't create the -wal/-shm sidecars). query_only guards writes.
+        uri = f"file:{self.db}?mode=rw"
+        for _ in range(120):  # wait for the harness to create the DB after spawn
+            try:
+                con = sqlite3.connect(uri, uri=True, timeout=2)
+                con.execute("PRAGMA query_only=1")
+                if con.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='events'").fetchone():
+                    return con
+                con.close()
+            except sqlite3.Error:
+                pass
+            if self._stopped.is_set():
+                break
+            time.sleep(0.3)
+        return None
+
+    def run(self) -> None:
+        con = self._connect()
+        if con is None:
+            return
+        last_seq = 0
+        last_hb = time.time()
+        draining = False
+        try:
+            while True:
+                try:
+                    for seq, kind, agent, data in con.execute(
+                        "SELECT seq, kind, agent, CAST(data AS TEXT) FROM events WHERE seq > ? ORDER BY seq",
+                        (last_seq,),
+                    ).fetchall():
+                        last_seq = seq
+                        try:
+                            d = json.loads(data) if data else {}
+                        except json.JSONDecodeError:
+                            d = {}
+                        mapped = map_event(kind, agent or "", d if isinstance(d, dict) else {})
+                        if mapped:
+                            self.em.emit(*mapped)
+                    if self.emit_findings:
+                        for fid, title, body, meta in con.execute(
+                            "SELECT id, title, body, coalesce(meta,'') FROM nodes WHERE kind='finding' AND status='confirmed' ORDER BY id"
+                        ).fetchall():
+                            if fid not in self.emitted:
+                                self.emitted.add(fid)
+                                self.em.emit("finding.created", finding_payload(
+                                    title, body, meta=parse_meta(meta), origin=self.origin,
+                                    con=con, checkout=self.checkout))
+                except sqlite3.Error:
+                    pass
+                now = time.time()
+                if now - last_hb >= HEARTBEAT_S:
+                    self.em.emit("heartbeat", {"uptimeMs": int((now - self.em.start_ts) * 1000)})
+                    last_hb = now
+                if draining:
+                    break
+                if self._stopped.is_set():
+                    draining = True  # one more pass drains the tail before exiting
+                time.sleep(0.6)
+        finally:
+            con.close()
+
+
+CHECKLISTS = Path(__file__).resolve().parent / "checklists"
+
+
+RECON_ENABLED = os.environ.get("BASIC_HARNESS_RECON", "1") != "0"
+
+
+def _coverage_floor() -> str:
+    """Render the checklist as a COVERAGE FLOOR appended to the brief.
+
+    This is deliberately framed as a floor, not a cage: it guarantees the standard
+    external attack surfaces are not skipped, while leaving the orchestrator free to
+    open novel directions beyond the list. The `web` surface is reachable through the
+    http op; the `recon` surface is included only when recon ops are enabled (Phase 2),
+    so the agent is never pointed at a capability it cannot call. Opt-in items (e.g.
+    token-gated code search) are omitted from the floor.
+    """
+    try:
+        data = json.loads((CHECKLISTS / "anonymous.json").read_text())
+    except (OSError, json.JSONDecodeError):
+        return ""
+    surfaces = data.get("surfaces") or {}
+    items = [i for i in surfaces.get("web", []) if not i.get("opt_in")]
+    if RECON_ENABLED:
+        items += [i for i in surfaces.get("recon", []) if not i.get("opt_in")]
+    floor = ""
+    if items:
+        lines = [f"- {i['title']}: {i['hint']}" for i in items]
+        floor = (
+            "\n\nCOVERAGE FLOOR (consider ALL of these surfaces; this is a floor, not a limit -- "
+            "pursue any other promising direction you find, and do NOT let the run orbit only this list):\n"
+            + "\n".join(lines)
+        )
+    return floor + _skill_index()
+
+
+def _skill_index() -> str:
+    """Advertise the on-demand deep playbooks (skill library). The index (name +
+    when-to-use) is cheap always-on context; the prober loads a full playbook with
+    the get_skill op only when a direction matches. Breadth stays with the coverage
+    floor above; skills add depth on demand (and the two will converge as more
+    surfaces become skills)."""
+    try:
+        import skills  # sibling module
+        idx = skills.render_index()
+    except Exception:  # noqa: BLE001 - never let the skill index break the brief
+        return ""
+    if not idx:
+        return ""
+    return ("\n\nDEEP PLAYBOOKS (load with the get_skill op): when a direction matches a playbook's "
+            "trigger below (e.g. GraphQL, IDOR, subdomain/takeover), you MUST FIRST call "
+            "get_skill with that playbook's name and follow its methodology before probing that "
+            "surface. These are detailed procedures, not a checklist:\n" + idx)
+
+
+def build_source_audit_brief(has_identities: bool) -> str:
+    """Mission for a SOURCE-ONLY (grey/white-box) target: a repository is connected but
+    there is NO reachable live host. The evidence is the code itself, so the audit is
+    driven through the reader (ask_reader -> list_files/grep/read_file), NOT live recon
+    against a placeholder host. Findings cite path:line, which the harness checks and the
+    patch flow consumes. Without this branch the brief points the team at a nonexistent
+    origin and the whole run finds nothing (see the 2026-10-30 zero-finding incident)."""
+    roles = ("You also have named application identities/roles (see list_identities): reason about "
+             "what each role can reach in the code versus what it should, and flag missing or broken "
+             "authorization checks.\n\n") if has_identities else ""
+    return (
+        "Perform a thorough SECURITY CODE AUDIT of the connected source repository. There is NO "
+        "running instance and NO reachable host -- do NOT attempt HTTP requests or external "
+        "reconnaissance; there is nothing to connect to and a probe only wastes the budget. Your "
+        "evidence is the SOURCE CODE itself.\n\n"
+        "Work through the reader (ask_reader -> list_files, grep, read_file). First MAP the app: its "
+        "entry points (routes/handlers/controllers/CLI), how untrusted input enters, how it flows to "
+        "dangerous sinks (SQL, shell/command, filesystem paths, deserialization, templates, HTTP "
+        "responses, redirects), and where authentication, authorization, and secret handling live. "
+        "Then HUNT for concrete vulnerabilities and trace each one from the untrusted source to the "
+        "sink.\n\n" + roles +
+        "Cover at least these classes: injection (SQLi, OS command, SSTI, path traversal, unsafe "
+        "deserialization), broken authentication / session handling, broken access control / IDOR / "
+        "missing authorization, SSRF, XSS, insecure or missing crypto, hardcoded secrets or "
+        "credentials, sensitive-data exposure, unsafe file upload/handling, open redirect, and "
+        "insecure configuration.\n\n"
+        "Report EACH distinct vulnerability you can substantiate with record_finding: name the "
+        "vulnerability class, cite the exact code location as path:line for every claim (the lines you "
+        "actually read), describe the source->sink data flow that makes it exploitable, and give the "
+        "concrete impact. Before confirming, follow the real code path and check for guards or "
+        "validation that would make it a false positive. Be exhaustive -- enumerate ALL the distinct "
+        "issues you can prove, not just the first few."
+    ) + _skill_index()
+
+
+def build_brief(spec: dict) -> str:
+    target_obj = spec.get("target") or {}
+    live_origins = target_obj.get("origins") or []
+    has_source = bool((target_obj.get("repository") or {}).get("checkoutPath"))
+    has_identities = bool(spec.get("identities"))
+
+    if spec.get("prompt"):
+        # Honor an explicit operator brief as the primary mission; still append the
+        # coverage floor so the wide net applies even to a custom-scoped run.
+        return str(spec["prompt"]) + _coverage_floor()
+
+    # Source-only (grey/white-box): a repo is connected but there is no reachable live
+    # origin (scope.allowedHosts carries only a sentinel like 'source-only.invalid').
+    # Audit the CODE through the reader rather than probing a host that does not exist.
+    if has_source and not live_origins:
+        return build_source_audit_brief(has_identities)
+
+    origins = live_origins or (spec.get("scope") or {}).get("allowedHosts") or []
+    target = origins[0] if origins else "the target application"
+
+    if has_identities:
+        mission = (
+            f"Assess {target} for security vulnerabilities and data exposure. You have named "
+            "identities (see list_identities): compare what each role CAN reach against what it "
+            "SHOULD, and report each demonstrated access-control / over-exposure violation with the "
+            "acting identity, the exact request, and the proving response. Identities are one lever, "
+            "not the whole job -- also probe the anonymous (unauthenticated) surface aggressively."
+        )
+    else:
+        # No credentials provisioned: this is the common case (most targets are anonymous
+        # by default). Pivot hard to the external-attacker surface instead of stalling on
+        # the absence of identities.
+        mission = (
+            f"Assess {target} as an external, unauthenticated attacker with NO credentials. This is "
+            "the normal starting posture -- do NOT treat the absence of identities as a blocker or an "
+            "excuse to stop; most real exposure is reachable anonymously. Hunt relentlessly across the "
+            "reachable surface and report each demonstrated vulnerability or data exposure with the "
+            "exact request and the proving response. External RECONNAISSANCE is REQUIRED, not optional: "
+            "you MUST use the recon ops to enumerate the verified root domain -- crt and dns for "
+            "subdomains and dangling/takeover records, storage for public buckets, registries for "
+            "public artifacts -- and then pivot http to the hosts you discover. Do not stop at the "
+            "primary origin."
+        )
+
+    grey = ""
+    if has_source:
+        # Grey-box: a live host AND a source checkout. Point the team at the reader so it
+        # corroborates what it sees over HTTP against the actual code (and finds issues the
+        # black-box surface hides), citing path:line.
+        grey = (" A READ-ONLY SOURCE CHECKOUT of this application is also connected: use ask_reader "
+                "(the reader reads the code and cites path:line) both to find vulnerabilities in the "
+                "code and to confirm or refute what you observe over HTTP -- corroborate every finding "
+                "against the actual code path.")
+    return mission + " This is a READ-ONLY assessment (GET/HEAD only)." + grey + _coverage_floor()
+
+
+def build_retest_brief(findings: list[dict]) -> str:
+    """A constrained brief for a RETEST run: re-verify each previously-confirmed finding
+    and judge only whether it still holds. No open-ended hunting -- the harness's validator
+    does the anti-false-positive work. Each finding is re-tested by the method it supports:
+    a finding with recorded env ops replays them; a CODE finding (a source location, no env
+    ops -- e.g. a source-only target, or a fix we just opened a PR for) is re-verified by
+    re-reading the cited code in the CURRENT checkout, which after a merge reflects the fix."""
+    lines = []
+    for i, f in enumerate(findings, 1):
+        title = (f.get("title") or "").strip()
+        desc = (f.get("description") or "").strip()
+        ops = (f.get("reproduction") or {}).get("ops") or []
+        src = f.get("source") or {}
+        if ops:
+            steps = "; ".join(
+                f"{o.get('op')} {json.dumps(o.get('args') or {}, separators=(',', ':'))}" for o in ops
+            )
+            how = f"RE-TEST (env): re-run these steps -- {steps}"
+        elif src.get("file"):
+            loc = str(src["file"]) + (f":{src['line']}" if src.get("line") else "")
+            how = (f"RE-TEST (code): this is a code finding at {loc}. Re-read that code in the CURRENT "
+                   "checkout with the reader (ask_reader -> list_files/grep/read_file) and decide whether "
+                   "the vulnerability is still present or has been fixed (input now validated/escaped, the "
+                   "sink guarded, or the vulnerable path removed).")
+        else:
+            how = "RE-TEST: reconstruct the check from the description above."
+        lines.append(f"{i}. TITLE: {title}\n   WHAT IT WAS: {desc[:500]}\n   {how}")
+    listing = "\n".join(lines)
+    return (
+        "RE-TEST MODE. The findings below were CONFIRMED on a previous assessment of this exact "
+        "target. Your ONLY job is to re-verify each one as-is; do NOT hunt for new issues.\n\n"
+        "For EACH finding, re-test it by the method noted (re-run the env steps, or re-read the cited "
+        "source in the current checkout), then judge from what you observe:\n"
+        "- If it STILL holds (the insecure behavior still happens, or the vulnerable code is still "
+        "present), record a finding with verdict CONFIRMED, using the EXACT title shown.\n"
+        "- If it appears FIXED (the behavior no longer occurs -- blocked/403/404, the leaked data is "
+        "gone, the mutation refused -- or the code now validates/guards the input or the vulnerable path "
+        "is gone), record verdict REFUTED with that title.\n"
+        "Cite the exact request and response, or the path:line, that shows the current behavior.\n\n"
+        f"FINDINGS TO RE-TEST:\n{listing}"
+    )
+
+
+def _match_original(title: str, findings: list[dict]) -> dict | None:
+    """Map a re-tested finding's (possibly paraphrased) title back to the original it
+    re-verifies: exact (case-insensitive) match first, then substring, then best token
+    overlap above a threshold. Returns the original finding dict or None."""
+    t = (title or "").strip().lower()
+    if not t:
+        return None
+    for f in findings:
+        if (f.get("title") or "").strip().lower() == t:
+            return f
+    tw = set(re.findall(r"[a-z0-9]+", t))
+    best, best_score = None, 0.0
+    for f in findings:
+        ft = (f.get("title") or "").strip().lower()
+        if not ft:
+            continue
+        if t in ft or ft in t:
+            return f
+        fw = set(re.findall(r"[a-z0-9]+", ft))
+        if tw and fw:
+            score = len(tw & fw) / len(tw | fw)
+            if score > best_score:
+                best, best_score = f, score
+    return best if best_score >= 0.6 else None
+
+
+def _run_remediate(spec: dict, em: "Emitter") -> int:
+    """Generate a code patch for ONE finding -- no harness run. Reads the finding's source
+    from the connected repo checkout, asks the model for a minimal unified diff, validates
+    it applies, and emits the patch on the finding; the control plane opens the PR."""
+    finding = (spec.get("remediate") or {}).get("finding") or {}
+    fp = finding.get("fingerprint")
+    checkout = ((spec.get("target") or {}).get("repository") or {}).get("checkoutPath")
+    if not fp or not (finding.get("source") or {}).get("file"):
+        em.emit("run.completed", {"stop": "halt", "findings": 0, "ok": True,
+                                  "message": "finding has no source location to patch"})
+        return 0
+    if not checkout:
+        em.emit("run.failed", {"category": "runtime",
+                               "message": "no source repository is connected; connect a repo to generate patches",
+                               "stop": "error"})
+        return 1
+    import remediate  # stdlib-only isolated patch generator; imported only for this kind
+    key = remediate.load_key(KEY_FILE)
+    gen_model = spec.get("model") or DEFAULT_REMEDIATE_MODEL
+    em.emit("phase.changed", {"phase": "remediating"})
+    patch = remediate.generate_patch(
+        checkout, finding, key, gen_model,
+        reviewer_model=DEFAULT_REMEDIATE_REVIEWER,
+        candidates=DEFAULT_REMEDIATE_CANDIDATES,
+    )
+    em.emit("finding.updated", {"fingerprint": fp, "title": finding.get("title") or "Finding", "patch": patch})
+    ok = patch.get("status") != "failed"
+    verified = patch.get("verified")
+    notes = (patch.get("review") or {}).get("notes") or ""
+    if not ok:
+        message = f"patch generation failed: {patch.get('error', '')}"
+    elif not patch.get("applies"):
+        message = "patch generated but did not apply cleanly; review the diff"
+    elif verified is True:
+        message = f"patch generated, reviewed, and applies cleanly ({patch.get('strategy', 'diff')})"
+    elif verified is False:
+        message = f"patch applies but the reviewer flagged it — review before merging{(': ' + notes) if notes else ''}"
+    else:
+        message = "patch generated and applies cleanly"
+    em.emit("run.completed", {"stop": "halt", "findings": 1 if ok else 0, "ok": True, "message": message})
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--spec", required=True)
+    ap.add_argument("--session-dir", required=True)
+    ap.add_argument("--events", default="stdout")
+    a = ap.parse_args()
+
+    spec = json.loads(Path(a.spec).read_text())
+    run_id = spec.get("runId") or "unknown"
+    em = Emitter(run_id)
+    session = Path(a.session_dir)
+    session.mkdir(parents=True, exist_ok=True)
+
+    # Policy gate: this runner is non-destructive only.
+    if bool((spec.get("policy") or {}).get("destructiveActions", False)):
+        em.emit("run.failed", {"category": "policy",
+                               "message": "basic-harness runner is read-only; destructiveActions must be false",
+                               "stop": "policy"})
+        return 3
+
+    # Egress gate (fail-closed): a RunSpec may require full network confinement.
+    # This adapter cannot confine itself, so unless the host signals it provides the
+    # jail (BLACKGLASS_EGRESS_CONFINED=1, set by a provisioned confined runner), we
+    # refuse rather than reach the target unconfined. 'best_effort' (local dev) runs.
+    if (spec.get("egress") or {}).get("isolation") == "required" and os.environ.get("BLACKGLASS_EGRESS_CONFINED") != "1":
+        em.emit("run.failed", {"category": "policy",
+                               "message": ("egress isolation 'required' but host confinement is not signaled "
+                                           "(set BLACKGLASS_EGRESS_CONFINED=1 on a confined runner); refusing to run unconfined"),
+                               "stop": "policy"})
+        return 3
+
+    origins = (spec.get("target") or {}).get("origins") or []
+    hosts = (spec.get("scope") or {}).get("allowedHosts") or []
+    # The run's primary origin, used to build each finding's absolute endpoint URL.
+    origin = origins[0] if origins else (hosts[0] if hosts else "")
+    profile = (spec.get("policy") or {}).get("profile", "safe")
+    isolation = (spec.get("egress") or {}).get("isolation", "best_effort")
+    em.emit("run.started", {
+        "runId": run_id, "origin": origin,
+        "hosts": hosts, "packs": spec.get("packs") or [], "profile": profile,
+        "isolation": isolation, "resumed": False, "ok": True,
+    })
+    em.emit("phase.changed", {"phase": "investigating"})
+
+    # Run kind: 'retest' re-verifies known findings (a constrained brief + fewer rounds)
+    # instead of the open-ended hunt; 'remediate' generates a patch for one finding (no
+    # harness run at all -- an isolated model call over the checkout); 'assess' (default)
+    # is the normal assessment.
+    kind = str(spec.get("kind") or "assess")
+    if kind == "remediate":
+        return _run_remediate(spec, em)
+    retest_findings = (spec.get("retest") or {}).get("findings") or [] if kind == "retest" else []
+    if kind == "retest" and not retest_findings:
+        em.emit("run.completed", {"stop": "halt", "findings": 0, "ok": True,
+                                  "message": "no findings with a reproduction recipe to retest"})
+        return 0
+    goal = build_retest_brief(retest_findings) if kind == "retest" else build_brief(spec)
+    rounds = (os.environ.get("BASIC_HARNESS_RETEST_ROUNDS", "1") if kind == "retest"
+              else os.environ.get("BASIC_HARNESS_ROUNDS", "3"))
+
+    # Scan depth profile (PR = fast/cheap gate, Full = deep audit): picks model
+    # placement, whether the council runs, breadth, and the cost backstop.
+    scan_name, prof = scan_profile_for(spec)
+
+    # A PR scan scopes to the pull request's diff when a base ref is available, so the
+    # fast gate reviews the change + its blast radius rather than the whole repo.
+    if scan_name == "pr" and kind == "assess":
+        _repo = (spec.get("target") or {}).get("repository") or {}
+        _base, _checkout = _repo.get("baseCommit"), _repo.get("checkoutPath")
+        if _base and _checkout:
+            _files = _pr_changed_files(str(_checkout), str(_base))
+            if _files:
+                goal = goal + _pr_scope_text(_files)
+
+    # Wall-clock budget is the PRIMARY stop condition (call/cost caps are off by default
+    # below). Prefer the RunSpec's policy.maxDurationMinutes; otherwise fall back to the
+    # profile's default (PR ~10 min, Full ~45 min). The harness enforces this itself via
+    # -max-time and stops GRACEFULLY at the deadline, reporting what it found; the external
+    # proc timeout further down is only a backstop, set a little longer so it wins.
+    policy_minutes = (spec.get("policy") or {}).get("maxDurationMinutes")
+    max_minutes = (float(policy_minutes) if isinstance(policy_minutes, (int, float)) and policy_minutes > 0
+                   else float(os.environ.get("BASIC_HARNESS_MAX_TIME_MIN", str(prof["default_minutes"]))))
+
+    # Posture pre-pass: on an assessment with a reachable origin, profile the public
+    # surface before the hunt. Its signals steer the agents (BLACKGLASS_PROFILE, consumed
+    # by prod_env) and its coverage + posture observations go into the report. Disabled by
+    # BASIC_HARNESS_PRESCAN=0; skipped for source-only (no origin) and retest/remediate.
+    prescan: dict | None = None
+    if (kind == "assess" and bool((spec.get("target") or {}).get("origins"))
+            and os.environ.get("BASIC_HARNESS_PRESCAN", "1") != "0"):
+        em.emit("phase.changed", {"phase": "profiling"})
+        tier = str((spec.get("policy") or {}).get("actionTier") or "passive")
+        prescan = run_prescan(a.spec, session, tier)
+        if prescan:
+            os.environ["BLACKGLASS_PROFILE"] = "1"
+            os.environ["BLACKGLASS_PROFILE_PATH"] = str(session / "profile.json")
+
+    # Test accounts: sign each username-and-password account in once, before the hunt, and
+    # hand the sessions to every agent's environment out-of-band (the environment, never
+    # disk), so all agents act as the account from their first request and share one
+    # session. A wrong password is tried once, not once per agent.
+    if (spec.get("target") or {}).get("origins"):
+        shared_sessions = sign_in_test_accounts(spec, em)
+        if shared_sessions:
+            os.environ["BLACKGLASS_SESSIONS_JSON"] = json.dumps(shared_sessions)
+
+    db = session / "agents.db"
+    cmd = [
+        HARNESS,
+        "-db", str(db),
+        "-goal", goal,
+        "-model", spec.get("model") or DEFAULT_MODEL,
+        # Exact argv (JSON) for the harness to exec directly -- no shell, so a PROD_ENV or
+        # spec path containing spaces survives intact. sys.executable (not literal python3)
+        # keeps the env on the same interpreter this controller runs under, which matters
+        # once a bundled runtime ships.
+        "-env", json.dumps([sys.executable, PROD_ENV, "--spec", a.spec]),
+        "-orchestrator", os.environ.get("BASIC_HARNESS_ORCHESTRATOR", prof["orchestrator"]),
+        "-rounds", rounds,
+        # Breadth from the scan profile: Full goes wide (the scaled arm that won the Juice
+        # Shop sweep, 2026-10-28); PR stays lighter for a fast gate. Env overrides for dev.
+        "-teams", os.environ.get("BASIC_HARNESS_TEAMS", prof["teams"]),
+        "-cells", os.environ.get("BASIC_HARNESS_CELLS", prof["cells"]),
+        "-team-calls", os.environ.get("BASIC_HARNESS_TEAM_CALLS", prof["team_calls"]),
+        "-workers", os.environ.get("BASIC_HARNESS_WORKERS", prof["workers"]),
+        # Bounded by WALL CLOCK, not calls: -max-time (set above) is the primary stop and
+        # the harness ends gracefully at the deadline. No call cap (0 = unlimited); the
+        # profile's cost backstop ($3 PR / $15 Full) guards a runaway without being the
+        # binding limit. An operator can still override any of these via env.
+        "-max-time", f"{max_minutes:g}m",
+        "-max-calls", os.environ.get("BASIC_HARNESS_MAX_CALLS", "0"),
+        "-max-cost", os.environ.get("BASIC_HARNESS_MAX_COST", prof["max_cost"]),
+        "-compact-tokens", "100000", "-ui", "", "-hold=false",
+    ]
+    # Route model calls through the murk model gateway when the control plane set
+    # OPENROUTER_BASE_URL (then OPENROUTER_API_KEY is a signed gateway token, not the
+    # OpenRouter key); direct to OpenRouter otherwise.
+    base_url = os.environ.get("OPENROUTER_BASE_URL", "").strip()
+    if base_url:
+        cmd += ["-base-url", base_url]
+    # Key resolution:
+    #  - Gateway mode (base_url set): OPENROUTER_API_KEY in the env is a SIGNED gateway token
+    #    that the harness must send as-is. A -key-file would override it with a raw OpenRouter
+    #    key (which the gateway rejects -> the harness fails its first model call and exits 1),
+    #    so NEVER pass a key file when routing through the gateway. This also stops a developer's
+    #    ~/Code/keys/.env from hijacking a hosted/local-scan run that already has a token.
+    #  - Direct mode (no gateway): prefer an explicit key file when one exists; otherwise the
+    #    harness reads OPENROUTER_API_KEY straight from the environment. Passing a -key-file that
+    #    does not exist is fatal, so only pass it when it is really there.
+    if not base_url and os.path.exists(KEY_FILE):
+        cmd += ["-key-file", KEY_FILE]
+    # Each team gets a validator agent that independently re-tests a candidate finding
+    # before the coordinator may confirm it (anti-false-positive). On by default; an
+    # operator can disable it for an A/B via BASIC_HARNESS_VALIDATE=0.
+    if os.environ.get("BASIC_HARNESS_VALIDATE", "1") != "0":
+        cmd.append("-validate")
+    repo = (spec.get("target") or {}).get("repository") or {}
+    if repo.get("checkoutPath"):
+        cmd += ["-source", str(repo["checkoutPath"])]
+    roles: dict[str, dict] = {}
+    if prof["coord_model"]:  # premium model at the synthesis locus (Full only)
+        roles["coordinator"] = {"model": prof["coord_model"]}
+    if prof["orch_model"]:  # glm-5.3 council chair + members (Full only; not k3)
+        roles["orchestrator"] = {"model": prof["orch_model"]}
+    if roles:
+        roles_file = session / "roles.json"
+        roles_file.write_text(json.dumps(roles))
+        cmd += ["-roles", str(roles_file)]
+    (session / "harness-cmd.txt").write_text(" ".join(cmd))
+
+    cancelled = {"flag": False}
+    proc: subprocess.Popen | None = None
+
+    def on_term(_signum, _frame):
+        cancelled["flag"] = True
+        if proc and proc.poll() is None:
+            proc.terminate()
+
+    signal.signal(signal.SIGTERM, on_term)
+
+    # The harness enforces the time box itself (-max-time = max_minutes, computed above)
+    # and stops gracefully. This external timeout is only a BACKSTOP for a harness that
+    # overruns its own deadline: set a little longer (grace) so the clean internal stop
+    # wins; on a hard expiry here we still salvage whatever findings exist.
+    timeout_s = max_minutes * 60 + 120
+
+    emitted_findings: set[int] = set()
+    follower = Follower(str(db), em, emitted_findings, emit_findings=(kind != "retest"), origin=origin,
+                        checkout=((spec.get("target") or {}).get("repository") or {}).get("checkoutPath"))
+    timed_out = False
+    with open(session / "harness.log", "w") as log:
+        proc = subprocess.Popen(cmd, cwd=str(ROOT), stdout=log, stderr=subprocess.STDOUT)
+        follower.start()  # tails the state DB and streams activity live
+        try:
+            code = proc.wait(timeout=timeout_s)
+        except subprocess.TimeoutExpired:
+            timed_out = True
+            proc.terminate()
+            try:
+                code = proc.wait(timeout=30)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                code = proc.wait()
+
+    follower.stop()
+    follower.join(timeout=10)
+
+    if cancelled["flag"]:
+        em.emit("run.cancelled", {"category": "cancelled", "message": "Run cancelled by operator"})
+        return 4
+
+    def _log_tail() -> str:
+        try:
+            return (session / "harness.log").read_text(errors="replace").strip()[-600:]
+        except OSError:
+            return ""
+
+    # Final reconcile: emit any confirmed finding the follower did not already stream.
+    # mode=rw (not a plain connect) so we never create a stray db, and if the harness
+    # produced no usable state DB (crashed / refused to start) surface ITS log rather
+    # than a confusing "no such table" SQLite error.
+    recs: list = []
+    run_cost: float | None = None
+    try:
+        con = sqlite3.connect(f"file:{db}?mode=rw", uri=True, timeout=5)
+        con.execute("PRAGMA query_only=1")
+        try:
+            rows = con.execute(
+                "SELECT id, title, body, coalesce(meta,'') FROM nodes WHERE kind='finding' AND status='confirmed' ORDER BY id"
+            ).fetchall()
+            # Build each finding's full payload while the DB is open: the model's
+            # assessment + the concrete, verbatim proof (cited request/response and code
+            # refs with snippets from the audited checkout). Reused for emission + report.
+            _checkout = ((spec.get("target") or {}).get("repository") or {}).get("checkoutPath")
+            recs = [
+                (fid, title, finding_payload(title, body, meta=parse_meta(meta), origin=origin,
+                                             con=con, checkout=_checkout))
+                for fid, title, body, meta in rows
+            ]
+            # The harness records the run's total spend in its terminal run.end event;
+            # surface it so the control plane can meter + bill the scan (usage ledger).
+            crow = con.execute(
+                "SELECT CAST(data AS TEXT) FROM events WHERE kind='run.end' ORDER BY seq DESC LIMIT 1"
+            ).fetchone()
+            if crow and crow[0]:
+                try:
+                    run_cost = float(json.loads(crow[0]).get("cost"))
+                except (ValueError, TypeError):
+                    run_cost = None
+        finally:
+            con.close()
+    except sqlite3.Error:
+        em.emit("run.failed", {"category": "runtime",
+                               "message": f"harness produced no findings DB (exit {code}): {_log_tail() or 'no output'}",
+                               "stop": "error"})
+        return 1
+    if kind == "retest":
+        # A re-confirmed finding (status 'confirmed' = still reproduces) is matched back
+        # to the original it re-verifies and re-emitted under the ORIGINAL fingerprint,
+        # verification='reproduced'. Originals with no match here were NOT reproduced; the
+        # control plane reconciles them to 'fixed' from the absence of an occurrence.
+        matched: set[str] = set()
+        for _fid, title, payload in recs:
+            orig = _match_original(title, retest_findings)
+            fp = orig.get("fingerprint") if orig else None
+            if not fp or fp in matched:
+                continue
+            matched.add(fp)
+            # Re-emit this run's fresh payload (incl. the re-reproduced proof) under the
+            # ORIGINAL finding's fingerprint/title so the control plane reconciles identity.
+            p = dict(payload)
+            p["fingerprint"] = fp
+            p["verification"] = "reproduced"
+            if orig.get("title"):
+                p["title"] = str(orig["title"])[:300]
+            em.emit("finding.updated", p)
+        n_findings = len(matched)
+    else:
+        for fid, _title, payload in recs:
+            if fid not in emitted_findings:
+                emitted_findings.add(fid)
+                em.emit("finding.created", payload)
+        n_findings = len(emitted_findings)
+
+    # On an assess run, a non-zero harness exit with zero findings is a failure; on a
+    # retest, zero re-confirmed findings is the SUCCESS case (everything was fixed).
+    if kind != "retest" and code != 0 and n_findings == 0 and not timed_out:
+        em.emit("run.failed", {"category": "runtime", "message": f"harness exited {code} with no findings",
+                               "stop": "error"})
+        return 1
+
+    # The customer report: deterministic sections (scope, severity rollup, each finding in
+    # full, the pre-scan's coverage + posture) plus an LLM-authored executive summary.
+    # Written to the session dir and served at /api/runs/:id/report. Produced for a
+    # completed/partial assessment (not a retest, and not a hard crash handled above).
+    if kind == "assess":
+        em.emit("phase.changed", {"phase": "reporting"})
+        report_model = (os.environ.get("BASIC_HARNESS_REPORT_MODEL")
+                        or prof.get("orch_model") or DEFAULT_MODEL)
+        write_report(session, run_id, spec, origin, scan_name, report_model, recs, prescan, em.start_ts)
+
+    completed = {
+        "stop": "timeout" if timed_out else "halt",
+        "findings": n_findings, "ok": True,
+        "scanProfile": scan_name,
+        "message": "time box reached; findings are partial" if timed_out else "",
+    }
+    if run_cost is not None:  # metered for billing by the control plane
+        completed["cost"] = run_cost
+    em.emit("run.completed", completed)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())