substratum-cli 0.1.0__py3-none-any.whl

substratum_cli/refusals.py

@@ -0,0 +1,127 @@
+"""The closed-class refusal template registry. Clinical-instrument voice: terse, no first
+person, no anthropomorphism. Every template produces all five mandatory elements including
+at least one executable flip command -- enforced by test. `from_engine` is the single door
+translating raw engine/gate codes into a CLI Refusal; unknown codes preserve the raw string
+under GATE_PRECONDITION (refuse-on-unknown, never invent a template).
+
+Two-owner flip discipline: YOUR-TESTS = the developer's actionable debt; SUBSTRATUM-COVERAGE
+= our gap, never dressed as theirs.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from . import codes
+from .result import FlipCondition, NextCommand, Refusal
+
+_PERMANENCE = "Retrying without changing inputs returns this exact refusal."
+
+# owner per code (fixed): coverage/driver gaps are ours; test-shaped gaps are theirs.
+_OWNER = {
+    codes.NO_GROUNDED_CANDIDATE: "SUBSTRATUM-COVERAGE",
+    codes.NO_DRIVER: "SUBSTRATUM-COVERAGE",
+    codes.AUTONOMY_LOCKED: "SUBSTRATUM-COVERAGE",
+    codes.GATE_PRECONDITION: "YOUR-TESTS",
+    codes.NO_WARRANT_TESTS: "YOUR-TESTS",
+    codes.HUNK_CONTEXT_STALE: "YOUR-TESTS",
+    codes.APPLY_STATE_DRIFT: "YOUR-TESTS",
+    codes.REPLAY_STATE_DRIFT: "YOUR-TESTS",
+    codes.UNDERDETERMINED_INTENT: "YOUR-TESTS",
+    codes.FLAKY_OR_VACUOUS_WARRANT: "YOUR-TESTS",
+    codes.FLAKY_TEST: "YOUR-TESTS",
+    codes.RUN_NOT_FOUND: "YOUR-TESTS",
+    codes.NO_ENGINE: "SUBSTRATUM-COVERAGE",
+}
+
+
+def _why(code: str, ctx: dict) -> str:
+    tgt = ctx.get("target", "the request")
+    return {
+        codes.NO_GROUNDED_CANDIDATE:
+            "no candidate in the current library grounds this request; coverage absent.",
+        codes.NO_DRIVER:
+            f"no gate runner or filetype driver applies to {tgt}.",
+        codes.AUTONOMY_LOCKED:
+            "this action requires an autonomy level above L1; it is locked in config.",
+        codes.GATE_PRECONDITION:
+            "the gate could not be executed cleanly (environment or harness).",
+        codes.NO_WARRANT_TESTS:
+            "verification requires at least one test to gate against; none supplied.",
+        codes.HUNK_CONTEXT_STALE:
+            "a diff hunk does not apply to the base; context has drifted.",
+        codes.APPLY_STATE_DRIFT:
+            "HEAD has moved since this run was produced; applying is unsafe.",
+        codes.REPLAY_STATE_DRIFT:
+            "repository state differs from the recorded run; replay cannot compare.",
+        codes.UNDERDETERMINED_INTENT:
+            "candidates were composed and every one failed the gate; the test does not "
+            "pin the intent uniquely.",
+        codes.FLAKY_OR_VACUOUS_WARRANT:
+            "the named tests pass at base in isolated replays; there is nothing to fix, "
+            "or the tests are nondeterministic.",
+        codes.FLAKY_TEST:
+            "the named test is on the quarantine list from the flake scan.",
+        codes.RUN_NOT_FOUND:
+            f"no stored run matches {tgt}.",
+        codes.NO_ENGINE:
+            "synthesis needs the engine, which is not available in this install; local commands "
+            "(summarize, verify, failing) still work offline.",
+    }.get(code, "refused.")
+
+
+def _flip_steps(code: str, ctx: dict) -> tuple[NextCommand, ...]:
+    tgt = ctx.get("target", "<target>")
+    if code in (codes.UNDERDETERMINED_INTENT, codes.NO_WARRANT_TESTS):
+        return (NextCommand("scaffold_test", tgt,
+                            f"substratum scaffold-test {tgt}"),
+                NextCommand("rerun_fix", tgt, f"substratum fix {tgt}"))
+    if code == codes.NO_GROUNDED_CANDIDATE:
+        return (NextCommand("scaffold_test", tgt,
+                            f"substratum scaffold-test {tgt}  # pin the behavior; coverage grows with data"),)
+    if code == codes.NO_ENGINE:
+        return (NextCommand("login", tgt,
+                            "substratum login  # use the hosted engine (nothing but intent leaves your machine)"),
+                NextCommand("install_engine", tgt,
+                            "pip install 'substratum-cli[engine]'  # or run the engine locally"))
+    if code == codes.NO_DRIVER:
+        return (NextCommand("provide_test_command", tgt,
+                            "substratum doctor  # inspect detected harness / configure drivers"),)
+    if code in (codes.FLAKY_OR_VACUOUS_WARRANT, codes.FLAKY_TEST):
+        return (NextCommand("repro", tgt, f"substratum doctor  # review quarantine for {tgt}"),)
+    if code in (codes.APPLY_STATE_DRIFT, codes.REPLAY_STATE_DRIFT):
+        return (NextCommand("show", tgt, f"substratum show {ctx.get('run_id','<run>')}  # inspect the recorded state"),)
+    if code == codes.GATE_PRECONDITION:
+        return (NextCommand("repro", tgt, "substratum doctor  # check harness, worktree, tmpdir"),)
+    if code == codes.AUTONOMY_LOCKED:
+        return (NextCommand("show", tgt, "substratum doctor  # shows effective .substratum.toml"),)
+    if code == codes.HUNK_CONTEXT_STALE:
+        return (NextCommand("rerun_fix", tgt, "git rebase; then re-run verify"),)
+    return (NextCommand("show", tgt, f"substratum show {ctx.get('run_id','<run>')}"),)
+
+
+def build(code: str, engine_code: str = "", ctx: Optional[dict] = None,
+          verified_before: tuple[str, ...] = ()) -> Refusal:
+    ctx = ctx or {}
+    owner = _OWNER.get(code, "SUBSTRATUM-COVERAGE")
+    return Refusal(
+        code=code, engine_code=engine_code or code, why=_why(code, ctx),
+        verified_before_refusing=verified_before,
+        flip=FlipCondition(owner=owner, steps=_flip_steps(code, ctx)),
+        permanence=_PERMANENCE,
+    )
+
+
+def from_engine(engine_code: str, ctx: Optional[dict] = None,
+                verified_before: tuple[str, ...] = ()) -> Refusal:
+    """The single mapping door: raw engine/gate code -> a complete Refusal."""
+    cli_code = codes.map_engine_code(engine_code)
+    return build(cli_code, engine_code=engine_code, ctx=ctx, verified_before=verified_before)
+
+
+def all_codes_have_flips() -> bool:
+    """The CI guard: every closed refusal code yields a complete refusal with an executable flip."""
+    for code in codes.REFUSAL_CODES:
+        r = build(code, ctx={"target": "x", "run_id": "sub_x"})
+        if not r.is_complete() or not any(s.command for s in r.flip.steps):
+            return False
+    return True

substratum_cli/remote.py

@@ -0,0 +1,140 @@
+"""The remote transport: when logged in, the thin client sends fix/write/clarify to the hosted
+engine (Fly) and renders the SAME SubstratumResult it would locally. The 6 GB library + the engine
+never ship; only focal snippets (fix) or the intent+signature (write) transit, over TLS. Stdlib
+`urllib` only -- the client stays dependency-free. Login is the GitHub device flow (no secret ships;
+the OAuth client-id is fetched from our server so it can rotate)."""
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+
+from . import account
+
+_GH_DEVICE_CODE = "https://github.com/login/device/code"
+_GH_ACCESS_TOKEN = "https://github.com/login/oauth/access_token"
+_UA = "substratum-cli"
+
+
+class RemoteError(Exception):
+    pass
+
+
+def enabled() -> bool:
+    """Remote mode is active iff the user is logged in (a token is present)."""
+    return account.is_logged_in()
+
+
+def _post_json(url: str, payload: dict, headers: dict | None = None, timeout: int = 30) -> dict:
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(url, data=data, method="POST")
+    req.add_header("Content-Type", "application/json")
+    req.add_header("Accept", "application/json")
+    req.add_header("User-Agent", _UA)
+    for k, v in (headers or {}).items():
+        req.add_header(k, v)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read().decode("utf-8") or "{}")
+    except urllib.error.HTTPError as e:
+        body = ""
+        try:
+            body = e.read().decode("utf-8")
+        except Exception:
+            pass
+        raise RemoteError(f"server returned {e.code}: {body[:200]}")
+    except urllib.error.URLError as e:
+        raise RemoteError(f"could not reach {url} ({e.reason})")
+
+
+def _get_json(url: str, headers: dict | None = None, timeout: int = 20) -> dict:
+    req = urllib.request.Request(url, method="GET")
+    req.add_header("Accept", "application/json")
+    req.add_header("User-Agent", _UA)
+    for k, v in (headers or {}).items():
+        req.add_header(k, v)
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.loads(r.read().decode("utf-8") or "{}")
+
+
+def _auth_headers() -> dict:
+    return {"Authorization": f"Bearer {account.token()}"}
+
+
+# ---- the engine calls (server returns the SAME SubstratumResult / candidate shapes) --------------
+def server_info() -> dict:
+    """GET /api/cli/version -> {engine_version, min_client, github_client_id}."""
+    return _get_json(account.server() + "/api/cli/version")
+
+
+def write(intent: str, signature: str, into: str | None = None,
+          prefer_purpose: str | None = None) -> dict:
+    """POST /api/cli/write -> a full SubstratumResult dict (server does synth + intrinsic verify)."""
+    return _post_json(account.server() + "/api/cli/write",
+                      {"intent": intent, "signature": signature, "into": into,
+                       "prefer_purpose": prefer_purpose}, _auth_headers())
+
+
+def clarify(intent: str, signature: str) -> dict:
+    """POST /api/cli/clarify -> {options: [...]} (needs the library)."""
+    return _post_json(account.server() + "/api/cli/clarify",
+                      {"intent": intent, "signature": signature}, _auth_headers())
+
+
+def candidate(test_ids: list, focal: dict) -> dict:
+    """POST /api/cli/candidate -> {status, diff, provenance, refuse_reason}. The server SYNTHESIZES;
+    the client gates the returned diff locally, so the user's code + tests never leave the machine."""
+    return _post_json(account.server() + "/api/cli/candidate",
+                      {"test_ids": list(test_ids), "focal": focal}, _auth_headers())
+
+
+# ---- GitHub device-flow login --------------------------------------------------------------------
+def login() -> dict:
+    """Run the GitHub device flow, exchange for a Substratum token, and persist it. Returns
+    {github_login}. Raises RemoteError with a clear message on any failure."""
+    info = server_info()
+    client_id = info.get("github_client_id")
+    if not client_id:
+        raise RemoteError("the server is not configured for login yet (no GitHub client id)")
+    dev = _post_json(_GH_DEVICE_CODE, {"client_id": client_id, "scope": "read:user"})
+    user_code = dev.get("user_code")
+    verify_uri = dev.get("verification_uri", "https://github.com/login/device")
+    device_code = dev.get("device_code")
+    interval = int(dev.get("interval", 5))
+    expires = int(dev.get("expires_in", 900))
+    if not (user_code and device_code):
+        raise RemoteError("GitHub did not return a device code")
+
+    print(f"\n  Open  {verify_uri}  and enter code:  {user_code}\n")
+    deadline = expires
+    waited = 0
+    gh_token = ""
+    while waited < deadline:
+        time.sleep(interval)
+        waited += interval
+        try:
+            r = _post_json(_GH_ACCESS_TOKEN, {
+                "client_id": client_id, "device_code": device_code,
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code"})
+        except RemoteError:
+            continue
+        if r.get("access_token"):
+            gh_token = r["access_token"]
+            break
+        err = r.get("error")
+        if err == "authorization_pending":
+            continue
+        if err == "slow_down":
+            interval += int(r.get("interval", 5))
+            continue
+        raise RemoteError(f"login failed: {err or 'unknown error'}")
+    if not gh_token:
+        raise RemoteError("login timed out; run `substratum login` again")
+
+    exch = _post_json(account.server() + "/api/cli/auth/exchange", {"github_token": gh_token})
+    tok = exch.get("token")
+    if not tok:
+        raise RemoteError("the server did not issue a token")
+    account.save(token=tok, github_login=exch.get("github_login", ""), server=account.server())
+    return {"github_login": exch.get("github_login", "")}

substratum_cli/render.py

@@ -0,0 +1,332 @@
+"""Human rendering in the Sovereign Seal design (see style.py). Line 1 is always the exact
+parseable grammar `<VERDICT>  run=<id>  [code=<CODE>]`; the body is a verdict-tinted rail closed
+by a foot seal, uppercase channel labels down a grey gutter, gold for the next executable move.
+Color law: green proven, cyan refused, gold next-action, grey chrome; red is tool-fault only.
+"""
+from __future__ import annotations
+
+import sys
+
+from . import codes
+from . import style as S
+from .result import SubstratumResult
+
+
+def _diff_file(diff: str) -> str:
+    """The file a diff touches (for the frame label). Prefers the +++ target, then the git header."""
+    import re
+    m = re.search(r"^\+\+\+ b/(.+)$", diff, re.M) or re.search(r"^diff --git a/\S+ b/(.+)$", diff, re.M)
+    return m.group(1).strip() if m else ""
+
+
+def render_human(res: SubstratumResult, stream=None, color: str | None = None) -> str:
+    stream = stream or sys.stdout
+    c = S.use_color(stream, color)
+    p = S.Painter(c)
+    vcol = S.verdict_color(res.verdict)
+    rail = p(S.g("rail"), vcol)
+    W = S.width()                      # everything (wraps, truncation) derives from the pane width
+    out: list[str] = []
+
+    def body(label: str, text: str, lab_col: str = S.LABEL, txt_col: str = "") -> None:
+        if text == "":       # a section header: no ljust padding, no trailing whitespace
+            out.append(f"{rail} {p(label, lab_col)}")
+        else:
+            out.append(f"{rail} {p(label.ljust(8), lab_col)} {p(text, txt_col) if txt_col else text}")
+
+    def bare() -> None:
+        out.append(rail)
+
+    # ---- line 1: the grammar, colored by verdict (bold verdict token) ----
+    head = res.summary
+    if c:
+        vb = (S.PROVEN_B if res.verdict in (codes.VERIFIED, codes.PASS)
+              else S.REFUSED_B if res.verdict in (codes.REFUSED, codes.UNVERIFIABLE)
+              else S.FAILC_B if res.verdict == codes.FAIL else vcol)
+        head = head.replace(res.verdict, p(res.verdict, vb), 1)
+    out.append(head)
+
+    # ---- streamed gate hero (proven runs) ----
+    if res.gate and res.gate.base_status:
+        arrow = p(S.g("arrow"), S.GOLD)
+        tests = ", ".join(res.gate.test_ids[:3]) or "warrant tests"
+        # color law: base FAIL is EXPECTED (chrome, never red); patched PASS is the proof (green)
+        base_c = p(res.gate.base_status, S.CHROME)
+        patched_c = p(res.gate.patched_status,
+                      S.PROVEN if res.gate.patched_status == "PASS" else S.FAULT)
+        body("GATE", f"{tests}: base {base_c} {arrow} patched {patched_c}")
+        if res.gate.impacted:
+            im = res.gate.impacted
+            body("IMPACT", f"{im.get('tests_run','?')} tests {S.g('dot')} "
+                           f"{im.get('regressions','?')} regressions")
+
+    # ---- verified fix / write: the change + provenance + next moves ----
+    if res.verdict in (codes.VERIFIED, codes.PASS) and res.diff and res.operation in ("fix", "write"):
+        bare()
+        fw = min(W, 82)
+        iw = fw - 4
+        diff_lines = []
+        for ln in res.diff.rstrip("\n").splitlines():
+            t = S.ellipsize(ln, iw)        # keep long code lines inside the box (full diff in `show`)
+            if ln.startswith("+") and not ln.startswith("+++"):
+                diff_lines.append(p(t, S.PROVEN))
+            elif ln.startswith("-") and not ln.startswith("---"):
+                diff_lines.append(p(t, S.CHROME))
+            elif ln.startswith("@@"):
+                diff_lines.append(p(t, S.GOLD))
+            else:
+                diff_lines.append(p(t, S.CHROME))
+        out.extend(S.frame(diff_lines, label=_diff_file(res.diff) or "change", width=fw, color=c))
+        if res.provenance and res.provenance.entries:
+            bare()
+            body("SOURCE", p(" " + S.g("dot") + " ", S.CHROME).join(res.provenance.entries[:4]),
+                 lab_col=S.GOLD)
+        if res.data and res.data.get("note"):
+            body("", p(res.data["note"], S.CHROME))
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+        rid = res.run_id
+        body_g = lambda lab, cmd: out.append(  # noqa: E731
+            f"  {p(lab.ljust(6), S.LABEL)} {p(cmd, S.GOLD)}")
+        if res.operation in ("fix", "write"):
+            body_g("apply", f"substratum apply {rid}")
+        body_g("proof", f"substratum show {rid}")
+        body_g("replay", f"substratum replay {rid}  {p(S.g('arrow'), S.GOLD)} byte-identical")
+
+    # ---- apply: the write moment -- show what landed + how to undo (never silent) ----
+    if res.operation == "apply" and res.verdict in (codes.VERIFIED, codes.PASS):
+        applied = list((res.data or {}).get("applied") or getattr(res, "files", ()) or ())
+        body("APPLIED", f"{len(applied)} file{'' if len(applied) == 1 else 's'} written",
+             lab_col=S.PROVEN)
+        for f in applied[:12]:
+            out.append(f"{rail}   {p(S.g('ok'), S.PROVEN)} {f}")
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+        if applied:
+            undo = "git checkout -- " + " ".join(applied[:3]) + (" …" if len(applied) > 3 else "")
+            out.append(f"  {p('undo'.ljust(6), S.LABEL)} {p(undo, S.GOLD)}")
+
+    # ---- per-hunk table (verify mixed diff) ----
+    if res.hunks:
+        bare()
+        for h in res.hunks:
+            hv = p(h.verdict, S.verdict_color(h.verdict))
+            body("HUNK", f"{h.path} {S.g('dot')} {hv}{(' ' + S.g('dot') + ' ' + h.code) if h.code else ''}")
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+
+    # ---- FAIL: the gate ran and the change did NOT pass -- show the captured failure + the move ----
+    if res.verdict == codes.FAIL and not res.hunks:
+        exc = ""
+        if res.gate:
+            exc = getattr(res.gate, "patched_excerpt", "") or getattr(res.gate, "base_excerpt", "")
+        if exc:
+            bare()
+            body("OUTPUT", "from the gate run", lab_col=S.FAILC)
+            for ln in exc.rstrip("\n").splitlines()[-8:]:
+                out.append(f"{rail}   {p(ln, S.CHROME)}")
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+        out.append(f"  {p('note'.ljust(6), S.LABEL)} "
+                   f"{p('the change does not satisfy the warrant; revise and re-verify', S.CHROME)}")
+
+    # ---- init: the Coverage Contract ----
+    if res.operation == "init" and res.data and "coverage_contract" in res.data:
+        cc = res.data["coverage_contract"]
+        body("HARNESS", cc.get("harness") or "none detected")
+        body("GATED", "", lab_col=S.PROVEN)
+        for r in cc.get("gated", [])[:16]:
+            lang = f" [{r['lang']}]" if r.get("lang") else ""
+            out.append(f"{rail}   {r['ext']}{lang}: {r['files']} files {S.g('dot')} {r['lines']} lines")
+        if cc.get("no_driver"):
+            body("REFUSES", "by name", lab_col=S.REFUSED)
+            for r in cc["no_driver"][:12]:
+                out.append(f"{rail}   {p(r['ext'] + ': ' + r['refusal'], S.REFUSED)}")
+        if res.data.get("air_gap"):
+            body("AIR-GAP", f"{res.data['air_gap']['sockets_opened']} sockets opened "
+                            f"({res.data['air_gap']['attestation']})")
+        if res.data.get("flake"):
+            body("FLAKE", f"suite stable across {res.data['flake']['rounds']} rounds: "
+                          f"{res.data['flake']['stable']}")
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+
+    if res.operation == "doctor" and res.data and "checks" in res.data:
+        for k, v in res.data["checks"].items():
+            label = k.replace("_", " ").upper()          # full label, not mid-word truncated
+            if isinstance(v, dict):
+                val = " " + S.g("dot") + " ".join(f"{kk} {vv}" for kk, vv in v.items())
+            else:
+                val = str(v)
+            ok = any(t in val.lower() for t in ("ok", "yes", "warm", "found",
+                                                "0 socket", "verified", "pass", "clean"))
+            body(label, p(val, S.PROVEN if ok else S.CHROME))
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+
+    if res.operation == "replay" and res.data:
+        bi = res.data.get("byte_identical"); sha = res.data.get("sha", "")
+        body("REPLAY", p(f"byte-identical: {'yes' if bi else 'no'}"
+                         + (f" (sha {sha[:12]})" if sha else ""), S.PROVEN if bi else S.FAULT))
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+
+    if res.operation == "explain" and res.data and "manifest" in res.data:
+        m = res.data["manifest"]
+        body("GRAIN", m.get("grain", ""))
+        for e in m.get("provenance", [])[:8]:
+            out.append(f"{rail}   {p(e, S.GOLD)}")
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+
+    if res.operation == "attest" and res.data:
+        body("BUNDLE", res.data.get("bundle", ""))
+        body("EGRESS", res.data.get("manifest", {}).get("egress", ""))
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+
+    # ---- failing: the failing tests discovered by running the repo's own suite ----
+    if res.operation == "failing" and res.data:
+        f = res.data.get("failing") or []
+        if f:
+            body("FAILING", f"{len(f)} failing test{'' if len(f) == 1 else 's'}", lab_col=S.FAILC)
+            bare()
+            for nid in f[:20]:
+                out.append(f"{rail}   {p(S.g('wall'), S.FAILC)} {S.ellipsize(nid, W - 6)}")
+            if len(f) > 20:
+                out.append(f"{rail}   {p(f'… and {len(f) - 20} more', S.CHROME)}")
+            out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+            out.append(f"  {p('fix'.ljust(6), S.LABEL)} {p('substratum fix ' + f[0], S.GOLD)}")
+        elif res.data.get("all_pass"):
+            body("TESTS", "all tests pass — nothing to fix", lab_col=S.PROVEN)
+            out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+        else:
+            body("TESTS", "the suite did not run cleanly", lab_col=S.CHROME)
+            for ln in (res.data.get("excerpt") or "").splitlines()[-6:]:
+                out.append(f"{rail}   {p(S.ellipsize(ln, W - 4), S.CHROME)}")
+            out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+
+    # ---- runs / log: the proof store made visible (history + conversion ledger) ----
+    if res.operation == "runs" and res.data:
+        led = res.data.get("ledger") or {}
+        refn, conv = led.get("refusals", 0), led.get("converted", 0)
+        if refn:
+            body("LEDGER", f"{conv} of {refn} refusals later converted to VERIFIED", lab_col=S.GOLD)
+        runs = res.data.get("runs") or []
+        if not runs:
+            body("RUNS", "no runs yet — try  fix  or  verify")
+        else:
+            bare()
+            for rn in runs:
+                vc = S.verdict_color(rn.get("verdict", ""))
+                vv = p(rn.get("verdict", "").ljust(8), vc)
+                target = S.ellipsize(rn.get("target", ""), max(10, W - 34))
+                tail = f"  {p(target, S.CHROME)}" if target else ""
+                out.append(f"{rail} {vv} {p(rn.get('run_id', ''), S.LABEL)}  "
+                           f"{rn.get('operation', '').ljust(6)}{tail}")
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+
+    # ---- undo: the inverse of apply (files restored) ----
+    if res.operation == "undo" and res.verdict in (codes.VERIFIED, codes.PASS):
+        rev = list((res.data or {}).get("reverted") or [])
+        body("REVERTED", f"{len(rev)} file{'' if len(rev) == 1 else 's'} restored", lab_col=S.PROVEN)
+        for f in rev[:12]:
+            out.append(f"{rail}   {p(S.g('ok'), S.PROVEN)} {f}")
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+
+    # ---- commit: the proof-carrying commit ----
+    if res.operation == "commit" and res.verdict in (codes.VERIFIED, codes.PASS):
+        d = res.data or {}
+        nf = len(d.get("files", []))
+        body("COMMITTED", f"{d.get('sha', '')} {S.g('dot')} {nf} file{'' if nf == 1 else 's'}",
+             lab_col=S.PROVEN)
+        if d.get("subject"):
+            body("SUBJECT", d["subject"])
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+
+    if res.operation == "scaffold_test" and res.data:
+        if res.diff:
+            bare()
+            for ln in res.diff.rstrip("\n").splitlines():
+                out.append(f"{rail}   {p(ln, S.CHROME)}")
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+        out.append(f"  {p('next'.ljust(6), S.LABEL)} {p(res.data.get('next', ''), S.GOLD)}")
+
+    # ---- summarize: the codebase in plain English, across every serviced language ----
+    if res.operation == "summarize" and res.data and "summary" in res.data:
+        sm = res.data["summary"]
+        about = sm.get("about")
+        if about and (about.get("name") or about.get("tagline") or about.get("blurb")):
+            import textwrap as _tw
+            fw = min(W, 74)
+            inner = []
+            if about.get("name"):
+                inner.append(p(about["name"], S.PROVEN_B))
+            for field in ("tagline", "blurb"):
+                if about.get(field):
+                    for w in _tw.wrap(about[field], fw - 4)[:4]:
+                        inner.append(w)
+            srcs = about.get("sources") or []
+            if srcs:
+                inner.append(p("grounded in " + (" " + S.g("dot") + " ").join(srcs), S.CHROME))
+            out.extend(S.frame(inner, label="ABOUT", width=fw, color=c))   # a light 'card' for the synopsis
+            bare()
+        langs = sm.get("languages") or {}
+        if sm.get("total_code_files") and langs:
+            brk = " ".join(f"{n} {k}" for k, n in sorted(langs.items(), key=lambda x: -x[1]))
+            plus = " +" if sm.get("truncated_files") else ""
+            body("CODEBASE", f"{sm['total_code_files']}{plus} files {S.g('dot')} {brk}")
+        parts = [f"{sm['functions']} functions"]
+        if sm.get("methods"):
+            parts.append(f"{sm['methods']} methods")
+        if sm.get("types"):
+            parts.append(f"{sm['types']} types")
+        body("SCOPE", (" " + S.g("dot") + " ").join(parts))
+        if sm.get("types_described"):
+            bare()
+            body("TYPES", "", lab_col=S.GOLD)
+            for d in sm["types_described"]:
+                eng = d.get("english") or d.get("symbol")
+                tag = f" [{d['lang']}]" if d.get("lang") else ""
+                meta = S.ellipsize(S.g('dot') + ' ' + d['symbol'] + '  ' + d['file'],
+                                   max(14, W - 5 - len(eng) - len(tag)))
+                out.append(f"{rail}   {p(eng, '')}{p(tag, S.CHROME)}  {p(meta, S.LABEL)}")
+        if sm.get("described"):
+            bare()
+            shown, trunc = sm.get("functions_shown", len(sm["described"])), sm.get("functions_truncated", 0)
+            lab = "FUNCTIONS" if not trunc else f"FUNCTIONS (top {shown} of {sm['functions']})"
+            body(lab, "", lab_col=S.GOLD)
+            for d in sm["described"]:
+                eng = d.get("english") or d.get("symbol")
+                tag = f" [{d['lang']}]" if d.get("lang") else ""
+                meta = S.ellipsize(S.g('dot') + ' ' + d['symbol'] + '  ' + d['file'],
+                                   max(14, W - 5 - len(eng) - len(tag)))
+                out.append(f"{rail}   {p(eng, '')}{p(tag, S.CHROME)}  {p(meta, S.LABEL)}")
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+        return "\n".join(out) + "\n"
+
+    # ---- the clarification ASK (ambiguous bare intent, plain-English options) ----
+    if res.data and res.data.get("clarify"):
+        cl = res.data["clarify"]
+        body("ASK", cl.get("question", "Which did you mean?"), lab_col=S.GOLD)
+        bare()
+        fw = min(W, 74)
+        inner = [p(str(i), S.GOLD) + "  " + S.ellipsize(o.get("text", ""), fw - 8)
+                 for i, o in enumerate(cl.get("options", [])[:6], 1)]
+        out.extend(S.frame(inner, label="options", width=fw, color=c))
+        intq, sigq = cl.get("intent", ""), cl.get("sig", "")
+        out.append(f"  {p('pick'.ljust(6), S.LABEL)} "
+                   f"{p(f'in a session, type the number', S.GOLD)}")
+        out.append(f"  {p('or'.ljust(6), S.LABEL)} "
+                   f"{p(f'write \"{intq}\" --sig \"{sigq}\" --mean \"<option>\"', S.GOLD)}")
+        return "\n".join(out) + "\n"
+
+    # ---- the Diligence Report (refusal) ----
+    if res.verdict in (codes.REFUSED, codes.UNVERIFIABLE) and res.refusal:
+        r = res.refusal
+        if r.verified_before_refusing:
+            body("CHECKED", "diligence performed before refusing")
+            for line in r.verified_before_refusing:
+                out.append(f"{rail}   {p(S.g('ok'), S.PROVEN)} {line}")
+        bare()
+        body("WHY", r.why, txt_col="")
+        bare()
+        body("FLIP", f"owner: {p(r.flip.owner, S.GOLD if r.flip.owner == 'YOUR-TESTS' else S.REFUSED)}")
+        for i, step in enumerate(r.flip.steps, 1):
+            out.append(f"{rail}   {p(str(i), S.GOLD)}  {p(step.command, S.GOLD)}")
+        bare()
+        body("STATE", p(r.permanence, S.CHROME))
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+
+    return "\n".join(out) + "\n"