@andresmassello/uscha 1.87.0 → 1.88.0

package/README.md

@@ -40,7 +40,7 @@ Requires **Python 3.8+** on the machine (the engine is Python stdlib — no pip
 runtime dependencies). The npm package is a thin router; the canonical installer is
 `uscha-kit/install-uscha.py`.
 
-**Kit v1.87.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.88.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
 [changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 
@@ -85,7 +85,7 @@ automatic tool can perform: a human verdict.
    from the compiled code: 0.062 measured (12 archetypes) — names, not yet semantics
 ```
 
-**What each arrow is, in the engine (kit 1.87.0, 52 subcommands, all measured):**
+**What each arrow is, in the engine (kit 1.88.0, 52 subcommands, all measured):**
 
 | Leg | Subcommands | What it establishes |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.87.0",
+  "version": "1.88.0",
   "description": "Spec-driven development for LLM coding agents: 9 skills + a stdlib evidence engine. Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",

package/uscha-kit/.claude/skills/uscha-devloop/qa_ledger.py

@@ -8232,6 +8232,168 @@ def _top_ac_key(cid):
         return (2, str(cid), 0)
 
 
+TOP_EVENTS_TAIL = 8          # how many steps the feed carries; the TUI shows what fits
+TOP_EVENT_WIDTH = 72         # one feed line, short enough to survive the 80-column floor
+
+# kind -> level, the FIXED map ADR-032 (amended 1.88.0, M2) requires. `level` and `text` do
+# not exist in `ledger["steps"]`; they are derived here, once, so the TUI renders a feed it
+# did not author (ADR-034). A kind absent from this map reads `info`: an unclassified step
+# is never a green one. Four kinds get their level REFINED below from the record the step
+# announces (the iteration/escalation with the same `n`, the k-th clean-room record of the
+# repo) -- and when that correlation misses, the level stays at its neutral value instead of
+# guessing a verdict.
+TOP_EVENT_LEVELS = {
+    "snapshot": "info",                      # -> fail when the snapshot recorded red tests
+    "qa-step": "info",                       # -> pass when nothing was reported, or all fixed
+    "static-gate": "info",                   # -> pass/fail by the gated finding count
+    "cleanroom": "info",                     # -> pass/fail by the record's `ok`
+    "fastpath-eval": "info",
+    "gate-not-run": "unmeasured",            # a gate nobody ran is UNMEASURED, not a pass
+    "escalation": "human",
+    "escalation-resolved": "human",
+    "production-finding": "human",
+    "production-finding:resolve": "human",
+    "spec-doubt": "human",
+    "spec-doubt:resolve": "human",
+    "spec-change-request": "human",
+    "spec-change-request:resolve": "human",
+}
+
+
+def _top_ts(iso):
+    """HH:MM:SS in UTC, or None. A stamp carrying an offset is normalized to UTC (machine-
+    independent); it is never converted to the LOCAL zone, which would make the same ledger
+    read differently on two boxes and break the golden frames."""
+    dt = _top_dt(iso)
+    if dt is None:
+        return None
+    if dt.tzinfo is not None:
+        dt = dt.astimezone(timezone.utc)
+    return dt.strftime("%H:%M:%S")
+
+
+def _top_key(value):
+    """A dict key that cannot raise. The writers always put a scalar in `n`, `at` and `repo`,
+    but the ledger is JSON on disk and a hand edit can leave a list or a dict there --
+    `unhashable type` is not how a read-only readout gets to report that."""
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return repr(value)
+
+
+def _top_event_text(*parts):
+    """One feed line: the only free text of the whole contract that reaches a terminal.
+
+    Its ingredients are ledger prose (an escalation reason, a tool name) -- human and CLI
+    input -- so an ESC or a C0 byte inside one would be a control sequence the board prints
+    verbatim. Every control character is dropped HERE, in the engine, and the renderer drops
+    them again on the way out: two cheap guards over one attack surface."""
+    txt = " · ".join(str(p) for p in parts if p not in (None, "", "?"))
+    txt = "".join(" " if c in ("\t", "\n", "\r") else c for c in txt)
+    txt = "".join(c for c in txt if ord(c) >= 32 and ord(c) != 127)
+    txt = " ".join(txt.split())
+    if len(txt) > TOP_EVENT_WIDTH:
+        txt = txt[:TOP_EVENT_WIDTH - 1] + "…"
+    return txt
+
+
+def _top_events(ledger, limit=TOP_EVENTS_TAIL):
+    """events_tail[]: the last `limit` steps as {ts, level, text}, NEWEST FIRST.
+
+    Deterministic given the ledger and read-only, like the rest of `cmd_top`. The step
+    records carry `n, at, kind, repo` plus a few per-kind fields; everything else the feed
+    shows comes from the record that step announces, correlated the way the ledger really
+    supports it: by `n` for iterations, escalations and fast-path entries (the writer copies
+    the counter into both), in ORDER for clean-room records (step and record are appended in
+    the same call), and by `(repo, at)` for snapshots. A miss degrades that one line to
+    `info` -- under-claiming a verdict, never inventing one."""
+    nodes = dict(ledger.get("repos") or {})
+    nodes["integration"] = ledger.get("integration") or {}
+    iters, snaps = {}, {}
+    for rname, node in nodes.items():
+        for it in (node or {}).get("iterations") or []:
+            if isinstance(it, dict) and it.get("n") is not None:
+                iters[(rname, _top_key(it.get("n")))] = it
+        for sn in (node or {}).get("snapshots") or []:
+            if isinstance(sn, dict):
+                snaps.setdefault((rname, _top_key(sn.get("at"))), sn)
+    esc = {_top_key(e.get("n")): e for e in ledger.get("escalations") or []
+           if isinstance(e, dict) and e.get("n") is not None}
+    fastp = {_top_key(e.get("n")): e for e in ledger.get("fast_path") or []
+             if isinstance(e, dict) and e.get("n") is not None}
+    crs = {}
+    for rec in ledger.get(CLEAN_ROOM_KEY) or []:
+        if isinstance(rec, dict):
+            crs.setdefault(str(rec.get("repo") or ""), []).append(rec)
+    cr_seen = {}
+
+    events = []
+    for st in ledger.get("steps") or []:
+        if not isinstance(st, dict):
+            continue
+        kind = str(st.get("kind") or "")
+        level = TOP_EVENT_LEVELS.get(kind, "info")
+        try:
+            repo = str(st.get("repo") or "")
+            n = _top_key(st.get("n"))
+            head, tail = kind or "step", None
+
+            if kind == "snapshot":
+                head = "snapshot " + repo if repo else "snapshot"
+                tail = "phase %s" % st.get("phase") if st.get("phase") else None
+                tests = (snaps.get((repo, _top_key(st.get("at")))) or {}).get("tests") or {}
+                red = (tests.get("failures") or 0) + (tests.get("errors") or 0)
+                if tests.get("report_found") and red:
+                    level, tail = "fail", "%d red test(s)" % red
+            elif kind in ("qa-step", "static-gate", "gate-not-run"):
+                head = "%s %s" % (kind, "/".join(str(p) for p in (repo, st.get("tool")) if p))
+                it = iters.get((repo, n)) or {}
+                rep, fixed = it.get("reported"), it.get("fixed")
+                gated = it.get("gated_reported")
+                if kind == "gate-not-run":
+                    tail = "not run — nobody measured it"
+                elif kind == "static-gate" and isinstance(gated, int):
+                    level = "fail" if gated >= 1 else "pass"
+                    tail = "%d gated finding(s)" % gated if gated else "clean"
+                elif kind == "qa-step" and isinstance(rep, int):
+                    if rep == 0 or (isinstance(fixed, int) and fixed >= rep):
+                        level = "pass"
+                    tail = "%d reported, %s fixed" % (rep,
+                                                      fixed if fixed is not None else "?")
+            elif kind == "cleanroom":
+                head = "cleanroom " + repo if repo else "cleanroom"
+                queue = crs.get(repo) or []
+                idx = cr_seen.get(repo, 0)
+                cr_seen[repo] = idx + 1
+                rec = queue[idx] if idx < len(queue) else {}
+                if rec.get("status") and rec.get("ok") is not None:
+                    level = "pass" if rec.get("ok") else "fail"
+                    tail = str(rec.get("status"))
+            elif kind == "fastpath-eval":
+                head = "fastpath-eval " + repo if repo else "fastpath-eval"
+                tail = (fastp.get(n) or {}).get("verdict")
+            elif kind in ("escalation", "escalation-resolved"):
+                head = "%s %s" % (kind, repo) if repo else kind
+                # `escalation-resolved` gets a FRESH counter of its own, so there is no
+                # record to look up: it says what happened and nothing more.
+                tail = (esc.get(n) or {}).get("reason") if kind == "escalation" else None
+            else:
+                head = "%s %s" % (kind, repo) if repo else (kind or "step")
+                tail = st.get("id")
+            text = _top_event_text(head, tail)
+        except Exception:
+            # a ledger is JSON on disk: any field can arrive as a list, a dict or a number
+            # from a hand edit. ONE unreadable step degrades to a neutral line naming its
+            # kind -- the readout never raises and never loses the JSON the board needs
+            # (the same fail-soft rule _top_dt already applies to timestamps).
+            level, text = "info", _top_event_text(kind or "step")
+
+        events.append({"ts": _top_ts(st.get("at")), "level": level, "text": text})
+
+    events.reverse()                          # newest first, as the board reads top-down
+    return events[:max(0, int(limit))]
+
+
 def cmd_top(args):
     """`uscha top` — the WHOLE projection of the ledger as one read-only JSON (ADR-032).
 
@@ -8348,7 +8510,9 @@ def cmd_top(args):
         "generated_at": _now(),
         "obligations": obligations,
         "observations": observations,
-        "events_tail": [],                # the live feed is M2; the key ships empty, not absent
+        # the live feed (M2): the last steps, newest first, with `level`/`text` derived by the
+        # fixed per-kind map above -- in the engine, so the TUI authors no verdict of its own.
+        "events_tail": _top_events(ledger),
         "counts": {"measured_pass": done, "measured_fail": fail, "quarantine": quar,
                    "unmeasured": _n("UNMEASURED"), "traced": 0, "tagged": 0, "total": total},
         "terminado": {"done": done, "total": total, "pct": pct, "unmeasured": unmeasured},

package/uscha-kit/.claude/skills/uscha-devloop/uscha_top.py

@@ -13,8 +13,8 @@ Truth-pass (INV-TOP-05): a field the engine emits as null renders as an em dash,
 zero and never as a guess. In v0.1 that is ETA, every AGE, drift, and the trace column --
 each with its deferred wiring recorded in ADR-035.
 
-M1 scope: the read-only BOARD. The live feed (M2) and VERDICTS mode (M3) are not wired; the
-panes that will hold them are labelled as such rather than faked.
+M2 scope: the read-only BOARD plus the live feed and its mtime poll. VERDICTS mode (M3) is
+not wired; the pane that will hold it is labelled as such rather than faked.
 
 Stdlib only. Python 3.8+. Runnable directly or via `python -m uscha_top`.
 """
@@ -25,6 +25,7 @@ import os
 import shutil
 import subprocess
 import sys
+import time
 
 DEFAULT_LEDGER = "QA-LEDGER.json"
 FALLBACK_SIZE = (100, 32)
@@ -32,8 +33,9 @@ FALLBACK_SIZE = (100, 32)
 # Lines the board always spends on chrome: the title, 3 rules, 4 KPI lines, the table
 # header, the feed label and the key hint. Everything else is table rows + feed.
 CHROME_LINES = 11
-FEED_MAX = 3
+FEED_MAX = 8            # = the engine's events_tail length; a short terminal shows fewer
 BURNUP_MAX = 24
+MIN_REFRESH = 0.5       # a poll faster than this is a busy loop, not a refresh
 
 # ANSI SGR by obligation state. TRACED and TAGGED deliberately share the UNMEASURED gray:
 # the v0.1 engine has no source for either rung (ADR-032), so they must read as "not
@@ -52,6 +54,19 @@ MID = "·"
 RULE = "─"
 BLOCKS = "▁▂▃▄▅▆▇█"
 
+# Feed levels: one letter and one colour each. The LETTER carries the level on the plain
+# path (golden frames, pipes, CI) and the colour only decorates that same letter on a real
+# terminal -- so both paths have identical geometry and a snapshot compares text, never
+# terminal control codes. `info` is deliberately uncoloured: it is the level an unclassified
+# step falls back to, and it must not look like a verdict.
+FEED_LEVELS = {
+    "pass": ("P", "32"),
+    "fail": ("F", "31"),
+    "human": ("H", "33"),
+    "unmeasured": ("U", "90"),
+    "info": ("I", ""),
+}
+
 # What the reader is expected to DO about a row. Presentation, not a KPI: no number here.
 ACTIONS = {
     "MEASURED_PASS": DASH,
@@ -121,12 +136,16 @@ def _burnup_line(burnup, cols):
 def _spec_pin_text(spec_pin):
     """git HEAD, labelled for what it is. There is no pinned-spec concept in the engine yet
     (ADR-035/4): an unverified sha must SAY it is unverified, and a non-git tree shows the
-    em dash rather than a fabricated pin (AC-T-06, INV-TOP-05)."""
+    em dash rather than a fabricated pin (AC-T-06, INV-TOP-05).
+
+    The sha is state-supplied text like any other, so it goes through `_safe`: it shares a
+    line with no colour of its own, but a frozen state carrying an escape here would put one
+    in the header, and the header is the one line every frame has."""
     if not spec_pin or not spec_pin.get("sha"):
         return "spec_pin " + DASH
     mark = ("clean-room verified" if spec_pin.get("clean_room_verified")
             else "not clean-room verified")
-    return "spec_pin %s (%s)" % (spec_pin["sha"], mark)
+    return "spec_pin %s (%s)" % (_safe(spec_pin["sha"]), mark)
 
 
 def _cases_text(ob):
@@ -139,11 +158,30 @@ def _cases_text(ob):
 def _row(ob, selected):
     gutter = "> " if selected else "  "
     return "%s%-8s%-9s%-15s%7s%5s  %s" % (
-        gutter, str(ob.get("id") or "?")[:8], str(ob.get("gate") or DASH)[:8],
-        str(ob.get("state") or "?")[:14], _cases_text(ob),
+        gutter, _safe(ob.get("id") or "?")[:8], _safe(ob.get("gate") or DASH)[:8],
+        _safe(ob.get("state") or "?")[:14], _cases_text(ob),
         _num(ob.get("age_hours")), ACTIONS.get(ob.get("state"), DASH))
 
 
+def _safe(text):
+    """No control character reaches the terminal through the feed. The engine already
+    strips them where the text is derived (`_top_event_text`); this is the second guard on
+    the same surface, because the renderer also accepts a frozen state file a human wrote,
+    and one ESC in it would be a control sequence the board obeys instead of prints."""
+    return "".join(c for c in str(text or "") if ord(c) >= 32 and ord(c) != 127)
+
+
+def _feed_line(ev, cols, plain):
+    """`HH:MM:SS  L  text` -- the level letter is the level, the colour only decorates it,
+    so the plain frame carries exactly the same information as the coloured one."""
+    letter, sgr = FEED_LEVELS.get(ev.get("level"), FEED_LEVELS["info"])
+    line = _fit("  %s  %s  %s" % (_safe(ev.get("ts")) or DASH, letter,
+                                  _safe(ev.get("text"))), cols)
+    if plain or not sgr:
+        return line
+    return line.replace("  %s  " % letter, "  \x1b[%sm%s%s  " % (sgr, letter, RESET), 1)
+
+
 def _colorize(line, state):
     code = PALETTE.get(state)
     if not code or state not in line:
@@ -167,9 +205,14 @@ def render(state, size, sel=0, plain=True):
     debtors = state.get("debtors") or {}
     honesty = state.get("honesty") or {}
 
+    # every string the STATE supplies goes through _safe on its way into a line (project,
+    # spec_pin, the row cells, the feed): after that the only escapes in a frame are the
+    # ones this renderer put there, which is what lets the final width pass leave coloured
+    # lines alone without a state file being able to smuggle one in (or widen a line).
     out = []
-    out.append(_spread("uscha top %s %s" % (MID, state.get("project") or "(unnamed project)"),
-                       "step #%s" % _num(state.get("step")), cols))
+    out.append(_spread("uscha top %s %s"
+                       % (MID, _safe(state.get("project")) or "(unnamed project)"),
+                       "step #%s" % _safe(_num(state.get("step"))), cols))
     out.append(RULE * cols)
     out.append(_pct_line(terminado))
     out.append("machine owes %s %s you owe %s %s untagged %s %s ETA %s"
@@ -177,9 +220,12 @@ def render(state, size, sel=0, plain=True):
                   _num(debtors.get("untagged")), MID, _num(state.get("eta_min"))))
     # honesty travels BESIDE done on purpose (INV-TOP-04): a thin denominator has to be
     # visible at the same glance as the number it flatters.
-    out.append("honesty %s/%s (%s%%) measured %s %s"
-               % (_num(honesty.get("measured")), _num(honesty.get("total")),
-                  _num(honesty.get("pct")), MID, _spec_pin_text(state.get("spec_pin"))))
+    # fitted HERE, at construction, not only by the pass at the end: this line carries the
+    # longest state-supplied string of the header, and the end pass skips coloured lines.
+    out.append(_fit("honesty %s/%s (%s%%) measured %s %s"
+                    % (_num(honesty.get("measured")), _num(honesty.get("total")),
+                       _num(honesty.get("pct")), MID,
+                       _spec_pin_text(state.get("spec_pin"))), cols))
     out.append(_burnup_line(state.get("burnup"), cols))
     out.append(RULE * cols)
     out.append("  %-8s%-9s%-15s%7s%5s  %s"
@@ -214,17 +260,31 @@ def render(state, size, sel=0, plain=True):
     pad = avail - len(table[:max(1, table_n)]) - feed_n
     out.extend([""] * max(0, pad))
     out.append(RULE * cols)
-    events = state.get("events_tail") or []
-    out.append("feed %s the live event tail is M2; nothing is invented here" % MID)
+    events = [e for e in (state.get("events_tail") or []) if isinstance(e, dict)]
+    shown = events[:feed_n]
+    if not events:
+        # honest empty label: a ledger with no steps has nothing to feed, and saying so is
+        # not the same statement as an idle feed with the lines scrolled away (INV-TOP-05).
+        out.append("feed %s no ledger step recorded yet (nothing to show)" % MID)
+    elif not shown:
+        # the board is served first (AC-T-21), so at the 80x24 floor with a long table the
+        # feed can lose every line. It says so; it does not pretend the ledger is quiet.
+        out.append("feed %s 0/%d %s no room at this size (the board is served first)"
+                   % (MID, len(events), MID))
+    else:
+        # `3/8` says out loud that the pane is showing three of the eight steps the engine
+        # sent: a feed that silently drops lines is a feed that can hide the red one.
+        out.append("feed %s %d/%d %s newest first %s P/F/H/U/I = pass/fail/human/"
+                   "unmeasured/info" % (MID, len(shown), len(events), MID, MID))
     for i in range(feed_n):
-        if i < len(events):
-            ev = events[i]
-            out.append(_fit("  %s  %s" % (ev.get("ts") or DASH, ev.get("text") or ""), cols))
-        else:
-            out.append("")
+        out.append(_feed_line(shown[i], cols, plain) if i < len(shown) else "")
     out.append("[j/k] move %s [r] reload %s [q] quit %s [v] verdicts (M3) %s "
                "[d]/[o] phase 2" % (MID, MID, MID, MID))
-    out = [_fit(line, cols) for line in out]
+    # a coloured line was already fitted BEFORE its escape bytes went in (table rows and
+    # feed lines both), and re-fitting it here would count those bytes as visible width --
+    # cutting the coloured frame ~9 characters shorter than the plain one it is supposed to
+    # match. Fit only what carries no escapes; the golden frames are that path exactly.
+    out = [line if "\x1b" in line else _fit(line, cols) for line in out]
     # exactly `rows` lines: a frame that drifts in height is a frame no snapshot can pin
     out = out[:rows] + [""] * max(0, rows - len(out))
     return out
@@ -313,6 +373,63 @@ def read_key():
         termios.tcsetattr(fd, termios.TCSADRAIN, saved)
 
 
+def wait_key(timeout):
+    """One keypress, or "" when `timeout` seconds pass first. This is what makes the poll
+    possible without a busy loop AND without a key that waits for the next tick to be seen:
+    POSIX blocks in `select` (raw mode held for the whole window, so a single byte is
+    readable the instant it arrives), Windows walks `msvcrt.kbhit` in short slices."""
+    if os.name == "nt":
+        import msvcrt
+        deadline = time.time() + max(0.0, timeout)
+        while True:
+            if msvcrt.kbhit():
+                return read_key()
+            if time.time() >= deadline:
+                return ""
+            time.sleep(0.03)
+    import select
+    import termios
+    import tty
+    fd = sys.stdin.fileno()
+    try:
+        saved = termios.tcgetattr(fd)
+    except Exception:
+        return ""                                    # no terminal to read: never block
+    try:
+        tty.setraw(fd)
+        ready, _, _ = select.select([sys.stdin], [], [], max(0.0, timeout))
+        return sys.stdin.read(1) if ready else ""
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+
+
+def _changed(paths, seen):
+    """(changed?, new snapshot) for a set of files, by (mtime, size).
+
+    The whole of the M2 poll: no server, no watcher, no thread (ADR-031). Kept as a small
+    pure-ish function on purpose -- it is the piece the suite can actually drive (AC-T-12),
+    while a real TTY session is not. A path that cannot be stat'ed records None instead of
+    raising: a ledger deleted under the app is a CHANGE, not a crash."""
+    now = {}
+    for path in paths or []:
+        if not path:
+            continue
+        try:
+            st = os.stat(path)
+            now[path] = (st.st_mtime, st.st_size)
+        except OSError:
+            now[path] = None
+    return now != (seen if seen is not None else {}), now
+
+
+def watch_paths(args):
+    """What the poll watches: the frozen state file when one is given, otherwise the ledger
+    the engine reads. Nothing else -- `discovery/CANDIDATE-DELTA.json` is NOT watched in
+    v0.1 (the state carries no path to it), so a `discover` run that leaves the ledger
+    untouched is seen on the next `r`, not on the next tick. Under-claim, then wire."""
+    return [args.state] if getattr(args, "state", None) else [getattr(args, "ledger", None)]
+
+
 def dispatch(key, sel, count):
     """Key -> (new selection, quit?, reload?). Pure, so the keymap is testable without a
     terminal: the driver below is not what is under test, this dispatch is (ADR-034)."""
@@ -339,20 +456,48 @@ def _print_frame(lines):
     sys.stdout.flush()
 
 
+def _reload(state, args):
+    """Re-read, or keep what is on screen. A poll that catches the ledger MID-WRITE reads a
+    truncated file; the last good board plus a retry next tick is honest, a traceback over
+    a working terminal is not."""
+    try:
+        return load_state(args.state, args.ledger)
+    except (OSError, ValueError, RuntimeError):
+        return state
+
+
 def _loop(state, args):
     sel = 0
+    interval = max(MIN_REFRESH, float(args.refresh or 0))
+    paths = watch_paths(args)
+    _seed, seen = _changed(paths, {})          # the first frame is already current
+    dirty = True
     sys.stdout.write("\x1b[?25l")
     try:
         while True:
-            frame = render(state, terminal_size(args.cols, args.rows), sel=sel, plain=False)
-            sys.stdout.write("\x1b[H\x1b[2J" + "\n".join(frame))
-            sys.stdout.flush()
-            sel, quit_now, reload_now = dispatch(
-                read_key(), sel, len(state.get("obligations") or []))
-            if quit_now:
-                return 0
-            if reload_now:
-                state = load_state(args.state, args.ledger)
+            if dirty:
+                frame = render(state, terminal_size(args.cols, args.rows),
+                               sel=sel, plain=False)
+                sys.stdout.write("\x1b[H\x1b[2J" + "\n".join(frame))
+                sys.stdout.flush()
+                dirty = False
+            # one wait serves both jobs: a key answers immediately, and the deadline is the
+            # `--refresh` tick that re-reads only when a watched file actually moved.
+            key = wait_key(interval)
+            if key:
+                sel, quit_now, reload_now = dispatch(
+                    key, sel, len(state.get("obligations") or []))
+                if quit_now:
+                    return 0
+                if reload_now:
+                    state = _reload(state, args)
+                    _fresh, seen = _changed(paths, seen)
+                dirty = True
+                continue
+            moved, seen = _changed(paths, seen)
+            if moved:
+                state = _reload(state, args)
+                dirty = True
     except KeyboardInterrupt:
         return 0
     finally:
@@ -374,7 +519,8 @@ def build_parser():
     parser.add_argument("--plain", action="store_true",
                         help="never emit escape sequences")
     parser.add_argument("--refresh", type=float, default=2.0,
-                        help="reserved for the M2 timed poll; M1 re-reads on the `r` key")
+                        help="seconds between mtime polls of the ledger (default: 2, "
+                             "floor %.1f); `r` still forces a re-read" % MIN_REFRESH)
     parser.add_argument("--cols", type=int, default=None)
     parser.add_argument("--rows", type=int, default=None)
     return parser

package/uscha-kit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.87.0",
+  "version": "1.88.0",
   "displayName": "Uscha",
   "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 52 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {

package/uscha-kit/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.87.0",
+  "version": "1.88.0",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",

package/uscha-kit/README.md

@@ -1,6 +1,6 @@
 # uscha-kit
 
-**Kit version:** v1.87.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.88.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.87.0
+uscha-kit 1.88.0

package/uscha-kit/reports/junit/.top-cases.json

@@ -1 +1 @@
-{"AC-T-01": true, "AC-T-02": true, "AC-T-03": true, "AC-T-10": true, "AC-T-04": true, "AC-T-05": true, "AC-T-06": true, "AC-T-09": true, "AC-T-24": true, "reg-quarantine-obs-null-on-measured": true, "reg-spec-pin-null-outside-worktree": true, "reg-unreachable-repo-named-not-silent": true, "AC-T-19": true, "reg-empty-project-honest": true, "AC-T-23": true, "AC-T-21": true, "AC-T-08": true, "AC-T-07": true, "AC-T-18": true, "AC-T-20": true, "AC-T-22": true, "reg-ledger-not-found": true}
+{"AC-T-01": true, "AC-T-02": true, "AC-T-03": true, "AC-T-10": true, "AC-T-04": true, "AC-T-05": true, "AC-T-06": true, "AC-T-09": true, "AC-T-24": true, "reg-quarantine-obs-null-on-measured": true, "reg-spec-pin-null-outside-worktree": true, "reg-unreachable-repo-named-not-silent": true, "reg-top-events-malformed-fields-degrade": true, "AC-T-11": true, "AC-T-19": true, "reg-empty-project-honest": true, "AC-T-23": true, "AC-T-21": true, "AC-T-08": true, "AC-T-07": true, "AC-T-18": true, "AC-T-20": true, "AC-T-22": true, "reg-ledger-not-found": true, "AC-T-12": true, "reg-top-render-state-text-cannot-widen-or-escape": true}

package/uscha-kit/skills/uscha-devloop/qa_ledger.py

@@ -8232,6 +8232,168 @@ def _top_ac_key(cid):
         return (2, str(cid), 0)
 
 
+TOP_EVENTS_TAIL = 8          # how many steps the feed carries; the TUI shows what fits
+TOP_EVENT_WIDTH = 72         # one feed line, short enough to survive the 80-column floor
+
+# kind -> level, the FIXED map ADR-032 (amended 1.88.0, M2) requires. `level` and `text` do
+# not exist in `ledger["steps"]`; they are derived here, once, so the TUI renders a feed it
+# did not author (ADR-034). A kind absent from this map reads `info`: an unclassified step
+# is never a green one. Four kinds get their level REFINED below from the record the step
+# announces (the iteration/escalation with the same `n`, the k-th clean-room record of the
+# repo) -- and when that correlation misses, the level stays at its neutral value instead of
+# guessing a verdict.
+TOP_EVENT_LEVELS = {
+    "snapshot": "info",                      # -> fail when the snapshot recorded red tests
+    "qa-step": "info",                       # -> pass when nothing was reported, or all fixed
+    "static-gate": "info",                   # -> pass/fail by the gated finding count
+    "cleanroom": "info",                     # -> pass/fail by the record's `ok`
+    "fastpath-eval": "info",
+    "gate-not-run": "unmeasured",            # a gate nobody ran is UNMEASURED, not a pass
+    "escalation": "human",
+    "escalation-resolved": "human",
+    "production-finding": "human",
+    "production-finding:resolve": "human",
+    "spec-doubt": "human",
+    "spec-doubt:resolve": "human",
+    "spec-change-request": "human",
+    "spec-change-request:resolve": "human",
+}
+
+
+def _top_ts(iso):
+    """HH:MM:SS in UTC, or None. A stamp carrying an offset is normalized to UTC (machine-
+    independent); it is never converted to the LOCAL zone, which would make the same ledger
+    read differently on two boxes and break the golden frames."""
+    dt = _top_dt(iso)
+    if dt is None:
+        return None
+    if dt.tzinfo is not None:
+        dt = dt.astimezone(timezone.utc)
+    return dt.strftime("%H:%M:%S")
+
+
+def _top_key(value):
+    """A dict key that cannot raise. The writers always put a scalar in `n`, `at` and `repo`,
+    but the ledger is JSON on disk and a hand edit can leave a list or a dict there --
+    `unhashable type` is not how a read-only readout gets to report that."""
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return repr(value)
+
+
+def _top_event_text(*parts):
+    """One feed line: the only free text of the whole contract that reaches a terminal.
+
+    Its ingredients are ledger prose (an escalation reason, a tool name) -- human and CLI
+    input -- so an ESC or a C0 byte inside one would be a control sequence the board prints
+    verbatim. Every control character is dropped HERE, in the engine, and the renderer drops
+    them again on the way out: two cheap guards over one attack surface."""
+    txt = " · ".join(str(p) for p in parts if p not in (None, "", "?"))
+    txt = "".join(" " if c in ("\t", "\n", "\r") else c for c in txt)
+    txt = "".join(c for c in txt if ord(c) >= 32 and ord(c) != 127)
+    txt = " ".join(txt.split())
+    if len(txt) > TOP_EVENT_WIDTH:
+        txt = txt[:TOP_EVENT_WIDTH - 1] + "…"
+    return txt
+
+
+def _top_events(ledger, limit=TOP_EVENTS_TAIL):
+    """events_tail[]: the last `limit` steps as {ts, level, text}, NEWEST FIRST.
+
+    Deterministic given the ledger and read-only, like the rest of `cmd_top`. The step
+    records carry `n, at, kind, repo` plus a few per-kind fields; everything else the feed
+    shows comes from the record that step announces, correlated the way the ledger really
+    supports it: by `n` for iterations, escalations and fast-path entries (the writer copies
+    the counter into both), in ORDER for clean-room records (step and record are appended in
+    the same call), and by `(repo, at)` for snapshots. A miss degrades that one line to
+    `info` -- under-claiming a verdict, never inventing one."""
+    nodes = dict(ledger.get("repos") or {})
+    nodes["integration"] = ledger.get("integration") or {}
+    iters, snaps = {}, {}
+    for rname, node in nodes.items():
+        for it in (node or {}).get("iterations") or []:
+            if isinstance(it, dict) and it.get("n") is not None:
+                iters[(rname, _top_key(it.get("n")))] = it
+        for sn in (node or {}).get("snapshots") or []:
+            if isinstance(sn, dict):
+                snaps.setdefault((rname, _top_key(sn.get("at"))), sn)
+    esc = {_top_key(e.get("n")): e for e in ledger.get("escalations") or []
+           if isinstance(e, dict) and e.get("n") is not None}
+    fastp = {_top_key(e.get("n")): e for e in ledger.get("fast_path") or []
+             if isinstance(e, dict) and e.get("n") is not None}
+    crs = {}
+    for rec in ledger.get(CLEAN_ROOM_KEY) or []:
+        if isinstance(rec, dict):
+            crs.setdefault(str(rec.get("repo") or ""), []).append(rec)
+    cr_seen = {}
+
+    events = []
+    for st in ledger.get("steps") or []:
+        if not isinstance(st, dict):
+            continue
+        kind = str(st.get("kind") or "")
+        level = TOP_EVENT_LEVELS.get(kind, "info")
+        try:
+            repo = str(st.get("repo") or "")
+            n = _top_key(st.get("n"))
+            head, tail = kind or "step", None
+
+            if kind == "snapshot":
+                head = "snapshot " + repo if repo else "snapshot"
+                tail = "phase %s" % st.get("phase") if st.get("phase") else None
+                tests = (snaps.get((repo, _top_key(st.get("at")))) or {}).get("tests") or {}
+                red = (tests.get("failures") or 0) + (tests.get("errors") or 0)
+                if tests.get("report_found") and red:
+                    level, tail = "fail", "%d red test(s)" % red
+            elif kind in ("qa-step", "static-gate", "gate-not-run"):
+                head = "%s %s" % (kind, "/".join(str(p) for p in (repo, st.get("tool")) if p))
+                it = iters.get((repo, n)) or {}
+                rep, fixed = it.get("reported"), it.get("fixed")
+                gated = it.get("gated_reported")
+                if kind == "gate-not-run":
+                    tail = "not run — nobody measured it"
+                elif kind == "static-gate" and isinstance(gated, int):
+                    level = "fail" if gated >= 1 else "pass"
+                    tail = "%d gated finding(s)" % gated if gated else "clean"
+                elif kind == "qa-step" and isinstance(rep, int):
+                    if rep == 0 or (isinstance(fixed, int) and fixed >= rep):
+                        level = "pass"
+                    tail = "%d reported, %s fixed" % (rep,
+                                                      fixed if fixed is not None else "?")
+            elif kind == "cleanroom":
+                head = "cleanroom " + repo if repo else "cleanroom"
+                queue = crs.get(repo) or []
+                idx = cr_seen.get(repo, 0)
+                cr_seen[repo] = idx + 1
+                rec = queue[idx] if idx < len(queue) else {}
+                if rec.get("status") and rec.get("ok") is not None:
+                    level = "pass" if rec.get("ok") else "fail"
+                    tail = str(rec.get("status"))
+            elif kind == "fastpath-eval":
+                head = "fastpath-eval " + repo if repo else "fastpath-eval"
+                tail = (fastp.get(n) or {}).get("verdict")
+            elif kind in ("escalation", "escalation-resolved"):
+                head = "%s %s" % (kind, repo) if repo else kind
+                # `escalation-resolved` gets a FRESH counter of its own, so there is no
+                # record to look up: it says what happened and nothing more.
+                tail = (esc.get(n) or {}).get("reason") if kind == "escalation" else None
+            else:
+                head = "%s %s" % (kind, repo) if repo else (kind or "step")
+                tail = st.get("id")
+            text = _top_event_text(head, tail)
+        except Exception:
+            # a ledger is JSON on disk: any field can arrive as a list, a dict or a number
+            # from a hand edit. ONE unreadable step degrades to a neutral line naming its
+            # kind -- the readout never raises and never loses the JSON the board needs
+            # (the same fail-soft rule _top_dt already applies to timestamps).
+            level, text = "info", _top_event_text(kind or "step")
+
+        events.append({"ts": _top_ts(st.get("at")), "level": level, "text": text})
+
+    events.reverse()                          # newest first, as the board reads top-down
+    return events[:max(0, int(limit))]
+
+
 def cmd_top(args):
     """`uscha top` — the WHOLE projection of the ledger as one read-only JSON (ADR-032).
 
@@ -8348,7 +8510,9 @@ def cmd_top(args):
         "generated_at": _now(),
         "obligations": obligations,
         "observations": observations,
-        "events_tail": [],                # the live feed is M2; the key ships empty, not absent
+        # the live feed (M2): the last steps, newest first, with `level`/`text` derived by the
+        # fixed per-kind map above -- in the engine, so the TUI authors no verdict of its own.
+        "events_tail": _top_events(ledger),
         "counts": {"measured_pass": done, "measured_fail": fail, "quarantine": quar,
                    "unmeasured": _n("UNMEASURED"), "traced": 0, "tagged": 0, "total": total},
         "terminado": {"done": done, "total": total, "pct": pct, "unmeasured": unmeasured},

package/uscha-kit/skills/uscha-devloop/uscha_top.py

@@ -13,8 +13,8 @@ Truth-pass (INV-TOP-05): a field the engine emits as null renders as an em dash,
 zero and never as a guess. In v0.1 that is ETA, every AGE, drift, and the trace column --
 each with its deferred wiring recorded in ADR-035.
 
-M1 scope: the read-only BOARD. The live feed (M2) and VERDICTS mode (M3) are not wired; the
-panes that will hold them are labelled as such rather than faked.
+M2 scope: the read-only BOARD plus the live feed and its mtime poll. VERDICTS mode (M3) is
+not wired; the pane that will hold it is labelled as such rather than faked.
 
 Stdlib only. Python 3.8+. Runnable directly or via `python -m uscha_top`.
 """
@@ -25,6 +25,7 @@ import os
 import shutil
 import subprocess
 import sys
+import time
 
 DEFAULT_LEDGER = "QA-LEDGER.json"
 FALLBACK_SIZE = (100, 32)
@@ -32,8 +33,9 @@ FALLBACK_SIZE = (100, 32)
 # Lines the board always spends on chrome: the title, 3 rules, 4 KPI lines, the table
 # header, the feed label and the key hint. Everything else is table rows + feed.
 CHROME_LINES = 11
-FEED_MAX = 3
+FEED_MAX = 8            # = the engine's events_tail length; a short terminal shows fewer
 BURNUP_MAX = 24
+MIN_REFRESH = 0.5       # a poll faster than this is a busy loop, not a refresh
 
 # ANSI SGR by obligation state. TRACED and TAGGED deliberately share the UNMEASURED gray:
 # the v0.1 engine has no source for either rung (ADR-032), so they must read as "not
@@ -52,6 +54,19 @@ MID = "·"
 RULE = "─"
 BLOCKS = "▁▂▃▄▅▆▇█"
 
+# Feed levels: one letter and one colour each. The LETTER carries the level on the plain
+# path (golden frames, pipes, CI) and the colour only decorates that same letter on a real
+# terminal -- so both paths have identical geometry and a snapshot compares text, never
+# terminal control codes. `info` is deliberately uncoloured: it is the level an unclassified
+# step falls back to, and it must not look like a verdict.
+FEED_LEVELS = {
+    "pass": ("P", "32"),
+    "fail": ("F", "31"),
+    "human": ("H", "33"),
+    "unmeasured": ("U", "90"),
+    "info": ("I", ""),
+}
+
 # What the reader is expected to DO about a row. Presentation, not a KPI: no number here.
 ACTIONS = {
     "MEASURED_PASS": DASH,
@@ -121,12 +136,16 @@ def _burnup_line(burnup, cols):
 def _spec_pin_text(spec_pin):
     """git HEAD, labelled for what it is. There is no pinned-spec concept in the engine yet
     (ADR-035/4): an unverified sha must SAY it is unverified, and a non-git tree shows the
-    em dash rather than a fabricated pin (AC-T-06, INV-TOP-05)."""
+    em dash rather than a fabricated pin (AC-T-06, INV-TOP-05).
+
+    The sha is state-supplied text like any other, so it goes through `_safe`: it shares a
+    line with no colour of its own, but a frozen state carrying an escape here would put one
+    in the header, and the header is the one line every frame has."""
     if not spec_pin or not spec_pin.get("sha"):
         return "spec_pin " + DASH
     mark = ("clean-room verified" if spec_pin.get("clean_room_verified")
             else "not clean-room verified")
-    return "spec_pin %s (%s)" % (spec_pin["sha"], mark)
+    return "spec_pin %s (%s)" % (_safe(spec_pin["sha"]), mark)
 
 
 def _cases_text(ob):
@@ -139,11 +158,30 @@ def _cases_text(ob):
 def _row(ob, selected):
     gutter = "> " if selected else "  "
     return "%s%-8s%-9s%-15s%7s%5s  %s" % (
-        gutter, str(ob.get("id") or "?")[:8], str(ob.get("gate") or DASH)[:8],
-        str(ob.get("state") or "?")[:14], _cases_text(ob),
+        gutter, _safe(ob.get("id") or "?")[:8], _safe(ob.get("gate") or DASH)[:8],
+        _safe(ob.get("state") or "?")[:14], _cases_text(ob),
         _num(ob.get("age_hours")), ACTIONS.get(ob.get("state"), DASH))
 
 
+def _safe(text):
+    """No control character reaches the terminal through the feed. The engine already
+    strips them where the text is derived (`_top_event_text`); this is the second guard on
+    the same surface, because the renderer also accepts a frozen state file a human wrote,
+    and one ESC in it would be a control sequence the board obeys instead of prints."""
+    return "".join(c for c in str(text or "") if ord(c) >= 32 and ord(c) != 127)
+
+
+def _feed_line(ev, cols, plain):
+    """`HH:MM:SS  L  text` -- the level letter is the level, the colour only decorates it,
+    so the plain frame carries exactly the same information as the coloured one."""
+    letter, sgr = FEED_LEVELS.get(ev.get("level"), FEED_LEVELS["info"])
+    line = _fit("  %s  %s  %s" % (_safe(ev.get("ts")) or DASH, letter,
+                                  _safe(ev.get("text"))), cols)
+    if plain or not sgr:
+        return line
+    return line.replace("  %s  " % letter, "  \x1b[%sm%s%s  " % (sgr, letter, RESET), 1)
+
+
 def _colorize(line, state):
     code = PALETTE.get(state)
     if not code or state not in line:
@@ -167,9 +205,14 @@ def render(state, size, sel=0, plain=True):
     debtors = state.get("debtors") or {}
     honesty = state.get("honesty") or {}
 
+    # every string the STATE supplies goes through _safe on its way into a line (project,
+    # spec_pin, the row cells, the feed): after that the only escapes in a frame are the
+    # ones this renderer put there, which is what lets the final width pass leave coloured
+    # lines alone without a state file being able to smuggle one in (or widen a line).
     out = []
-    out.append(_spread("uscha top %s %s" % (MID, state.get("project") or "(unnamed project)"),
-                       "step #%s" % _num(state.get("step")), cols))
+    out.append(_spread("uscha top %s %s"
+                       % (MID, _safe(state.get("project")) or "(unnamed project)"),
+                       "step #%s" % _safe(_num(state.get("step"))), cols))
     out.append(RULE * cols)
     out.append(_pct_line(terminado))
     out.append("machine owes %s %s you owe %s %s untagged %s %s ETA %s"
@@ -177,9 +220,12 @@ def render(state, size, sel=0, plain=True):
                   _num(debtors.get("untagged")), MID, _num(state.get("eta_min"))))
     # honesty travels BESIDE done on purpose (INV-TOP-04): a thin denominator has to be
     # visible at the same glance as the number it flatters.
-    out.append("honesty %s/%s (%s%%) measured %s %s"
-               % (_num(honesty.get("measured")), _num(honesty.get("total")),
-                  _num(honesty.get("pct")), MID, _spec_pin_text(state.get("spec_pin"))))
+    # fitted HERE, at construction, not only by the pass at the end: this line carries the
+    # longest state-supplied string of the header, and the end pass skips coloured lines.
+    out.append(_fit("honesty %s/%s (%s%%) measured %s %s"
+                    % (_num(honesty.get("measured")), _num(honesty.get("total")),
+                       _num(honesty.get("pct")), MID,
+                       _spec_pin_text(state.get("spec_pin"))), cols))
     out.append(_burnup_line(state.get("burnup"), cols))
     out.append(RULE * cols)
     out.append("  %-8s%-9s%-15s%7s%5s  %s"
@@ -214,17 +260,31 @@ def render(state, size, sel=0, plain=True):
     pad = avail - len(table[:max(1, table_n)]) - feed_n
     out.extend([""] * max(0, pad))
     out.append(RULE * cols)
-    events = state.get("events_tail") or []
-    out.append("feed %s the live event tail is M2; nothing is invented here" % MID)
+    events = [e for e in (state.get("events_tail") or []) if isinstance(e, dict)]
+    shown = events[:feed_n]
+    if not events:
+        # honest empty label: a ledger with no steps has nothing to feed, and saying so is
+        # not the same statement as an idle feed with the lines scrolled away (INV-TOP-05).
+        out.append("feed %s no ledger step recorded yet (nothing to show)" % MID)
+    elif not shown:
+        # the board is served first (AC-T-21), so at the 80x24 floor with a long table the
+        # feed can lose every line. It says so; it does not pretend the ledger is quiet.
+        out.append("feed %s 0/%d %s no room at this size (the board is served first)"
+                   % (MID, len(events), MID))
+    else:
+        # `3/8` says out loud that the pane is showing three of the eight steps the engine
+        # sent: a feed that silently drops lines is a feed that can hide the red one.
+        out.append("feed %s %d/%d %s newest first %s P/F/H/U/I = pass/fail/human/"
+                   "unmeasured/info" % (MID, len(shown), len(events), MID, MID))
     for i in range(feed_n):
-        if i < len(events):
-            ev = events[i]
-            out.append(_fit("  %s  %s" % (ev.get("ts") or DASH, ev.get("text") or ""), cols))
-        else:
-            out.append("")
+        out.append(_feed_line(shown[i], cols, plain) if i < len(shown) else "")
     out.append("[j/k] move %s [r] reload %s [q] quit %s [v] verdicts (M3) %s "
                "[d]/[o] phase 2" % (MID, MID, MID, MID))
-    out = [_fit(line, cols) for line in out]
+    # a coloured line was already fitted BEFORE its escape bytes went in (table rows and
+    # feed lines both), and re-fitting it here would count those bytes as visible width --
+    # cutting the coloured frame ~9 characters shorter than the plain one it is supposed to
+    # match. Fit only what carries no escapes; the golden frames are that path exactly.
+    out = [line if "\x1b" in line else _fit(line, cols) for line in out]
     # exactly `rows` lines: a frame that drifts in height is a frame no snapshot can pin
     out = out[:rows] + [""] * max(0, rows - len(out))
     return out
@@ -313,6 +373,63 @@ def read_key():
         termios.tcsetattr(fd, termios.TCSADRAIN, saved)
 
 
+def wait_key(timeout):
+    """One keypress, or "" when `timeout` seconds pass first. This is what makes the poll
+    possible without a busy loop AND without a key that waits for the next tick to be seen:
+    POSIX blocks in `select` (raw mode held for the whole window, so a single byte is
+    readable the instant it arrives), Windows walks `msvcrt.kbhit` in short slices."""
+    if os.name == "nt":
+        import msvcrt
+        deadline = time.time() + max(0.0, timeout)
+        while True:
+            if msvcrt.kbhit():
+                return read_key()
+            if time.time() >= deadline:
+                return ""
+            time.sleep(0.03)
+    import select
+    import termios
+    import tty
+    fd = sys.stdin.fileno()
+    try:
+        saved = termios.tcgetattr(fd)
+    except Exception:
+        return ""                                    # no terminal to read: never block
+    try:
+        tty.setraw(fd)
+        ready, _, _ = select.select([sys.stdin], [], [], max(0.0, timeout))
+        return sys.stdin.read(1) if ready else ""
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+
+
+def _changed(paths, seen):
+    """(changed?, new snapshot) for a set of files, by (mtime, size).
+
+    The whole of the M2 poll: no server, no watcher, no thread (ADR-031). Kept as a small
+    pure-ish function on purpose -- it is the piece the suite can actually drive (AC-T-12),
+    while a real TTY session is not. A path that cannot be stat'ed records None instead of
+    raising: a ledger deleted under the app is a CHANGE, not a crash."""
+    now = {}
+    for path in paths or []:
+        if not path:
+            continue
+        try:
+            st = os.stat(path)
+            now[path] = (st.st_mtime, st.st_size)
+        except OSError:
+            now[path] = None
+    return now != (seen if seen is not None else {}), now
+
+
+def watch_paths(args):
+    """What the poll watches: the frozen state file when one is given, otherwise the ledger
+    the engine reads. Nothing else -- `discovery/CANDIDATE-DELTA.json` is NOT watched in
+    v0.1 (the state carries no path to it), so a `discover` run that leaves the ledger
+    untouched is seen on the next `r`, not on the next tick. Under-claim, then wire."""
+    return [args.state] if getattr(args, "state", None) else [getattr(args, "ledger", None)]
+
+
 def dispatch(key, sel, count):
     """Key -> (new selection, quit?, reload?). Pure, so the keymap is testable without a
     terminal: the driver below is not what is under test, this dispatch is (ADR-034)."""
@@ -339,20 +456,48 @@ def _print_frame(lines):
     sys.stdout.flush()
 
 
+def _reload(state, args):
+    """Re-read, or keep what is on screen. A poll that catches the ledger MID-WRITE reads a
+    truncated file; the last good board plus a retry next tick is honest, a traceback over
+    a working terminal is not."""
+    try:
+        return load_state(args.state, args.ledger)
+    except (OSError, ValueError, RuntimeError):
+        return state
+
+
 def _loop(state, args):
     sel = 0
+    interval = max(MIN_REFRESH, float(args.refresh or 0))
+    paths = watch_paths(args)
+    _seed, seen = _changed(paths, {})          # the first frame is already current
+    dirty = True
     sys.stdout.write("\x1b[?25l")
     try:
         while True:
-            frame = render(state, terminal_size(args.cols, args.rows), sel=sel, plain=False)
-            sys.stdout.write("\x1b[H\x1b[2J" + "\n".join(frame))
-            sys.stdout.flush()
-            sel, quit_now, reload_now = dispatch(
-                read_key(), sel, len(state.get("obligations") or []))
-            if quit_now:
-                return 0
-            if reload_now:
-                state = load_state(args.state, args.ledger)
+            if dirty:
+                frame = render(state, terminal_size(args.cols, args.rows),
+                               sel=sel, plain=False)
+                sys.stdout.write("\x1b[H\x1b[2J" + "\n".join(frame))
+                sys.stdout.flush()
+                dirty = False
+            # one wait serves both jobs: a key answers immediately, and the deadline is the
+            # `--refresh` tick that re-reads only when a watched file actually moved.
+            key = wait_key(interval)
+            if key:
+                sel, quit_now, reload_now = dispatch(
+                    key, sel, len(state.get("obligations") or []))
+                if quit_now:
+                    return 0
+                if reload_now:
+                    state = _reload(state, args)
+                    _fresh, seen = _changed(paths, seen)
+                dirty = True
+                continue
+            moved, seen = _changed(paths, seen)
+            if moved:
+                state = _reload(state, args)
+                dirty = True
     except KeyboardInterrupt:
         return 0
     finally:
@@ -374,7 +519,8 @@ def build_parser():
     parser.add_argument("--plain", action="store_true",
                         help="never emit escape sequences")
     parser.add_argument("--refresh", type=float, default=2.0,
-                        help="reserved for the M2 timed poll; M1 re-reads on the `r` key")
+                        help="seconds between mtime polls of the ledger (default: 2, "
+                             "floor %.1f); `r` still forces a re-read" % MIN_REFRESH)
     parser.add_argument("--cols", type=int, default=None)
     parser.add_argument("--rows", type=int, default=None)
     return parser

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.87.0",
+  "version": "1.88.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,