@r1z4x/tezgah 1.6.0 → 1.8.2

package/hooks/tezgah_models.py

@@ -37,6 +37,7 @@ tier from the static table, and with no phase the middle tier is used.
 
 Stdlib only; every network or subprocess failure is a fallback, never a raise.
 """
+import contextlib
 import datetime
 import json
 import os
@@ -232,18 +233,331 @@ def _omp_stored_providers():
     return {row[0] for row in rows}
 
 
-def funded_families():
+def funded_families(live=True):
     """The `OMP_FAMILIES` with a credential this machine shows: an omp auth-store
-    entry, an env key omp reads, or (for `any`) `openrouter_ready`.
+    entry, an env key omp reads, or (for `any`) `openrouter_ready` - minus, with
+    `live`, the families the health record holds as down (`down_families`).
 
     A credential is not a balance - a funded-looking key can still answer 402 -
-    which is why each agent gets a chain rather than one more pin. A family whose
-    credential cannot be detected is left out, never guessed in."""
+    which is why each agent gets a chain rather than one more pin, and why a
+    family whose provider answered a limit leaves the chain until its reset. A
+    family whose credential cannot be detected is left out, never guessed in."""
     stored = _omp_stored_providers()
+    down = down_families() if live else set()
     return [family for family in OMP_FAMILIES
-            if OMP_AUTH[family][0] in stored
-            or any(os.environ.get(env, "").strip() for env in OMP_AUTH[family][1])
-            or (family == "any" and openrouter_ready())]
+            if family not in down
+            and (OMP_AUTH[family][0] in stored
+                 or any(os.environ.get(env, "").strip() for env in OMP_AUTH[family][1])
+                 or (family == "any" and openrouter_ready()))]
+
+
+# ------------------------------------------------------------ provider health
+#
+# A family with a credential can still be spent: on 2026-10-11 every subagent
+# chain read `anthropic, openrouter`, one Anthropic 429 moved the subagents onto
+# an OpenRouter key past its limit (403), and they died; zai, funded in omp's
+# store, answered `429 Weekly/Monthly Limit Exhausted. Your limit will reset at
+# 2026-10-12 02:02:35`. The record below holds which family is down and until
+# when; `funded_families` leaves those out, and `tezgah-route --health` - started
+# in the background at session start when due - probes the non-mode families
+# and re-applies omp's chain, so a family rejoins it once its reset has passed.
+HEALTH_FILE = "model-health.json"
+HEALTH_EVERY = 6 * 3600       # re-probe at most this often, unless a reset passed
+HEALTH_DOWN = 6 * 3600        # how long a limit with no reset time keeps a family out
+HEALTH_RATE = 600             # the same for a rate limit (429): it lifts in minutes
+HEALTH_DOWN_MAX = 7 * 86400   # the longest a named reset is believed
+OPENROUTER_KEY = "https://openrouter.ai/api/v1/key"
+_RESET_AT = re.compile(r"reset[s]? (?:at|on) (\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}:\d{2})")
+_RETRY_MS = re.compile(r"retry-after-ms=(\d+)")
+_LIMITED = re.compile(r"\b(?:429|402|403)\b|rate[ _-]?limit|quota|limit exhausted|"
+                      r"key limit exceeded|usage limit|insufficient (?:credit|balance)",
+                      re.I)
+
+
+def _health_path():
+    return os.path.join(tp.cache_dir(), HEALTH_FILE)
+
+
+def read_health():
+    """{"checked": epoch or None, "down": {family: {"until": epoch, "reason": str}}};
+    an unreadable record reads as empty - nothing known down."""
+    try:
+        with open(_health_path(), encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError):
+        data = {}
+    if not isinstance(data, dict):
+        data = {}
+    down = data.get("down") if isinstance(data.get("down"), dict) else {}
+    return {"checked": data.get("checked"), "down": down}
+
+
+def write_health(data):
+    """Write the record atomically; False when the cache dir cannot be written."""
+    path = _health_path()
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        tmp = "%s.%d.tmp" % (path, os.getpid())
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, indent=1, sort_keys=True)
+        os.replace(tmp, path)
+        return True
+    except OSError:
+        return False
+
+
+def down_families(now=None, data=None):
+    """The families the record holds as down whose reset has not passed yet."""
+    import time
+    now = time.time() if now is None else now
+    data = read_health() if data is None else data
+    return {family for family, row in data["down"].items()
+            if isinstance(row, dict) and isinstance(row.get("until"), (int, float))
+            and row["until"] > now}
+
+
+def limit_until(text, now=None, default=HEALTH_DOWN):
+    """When a provider's limit answer says it lifts, as an epoch, or None when the
+    text is no limit answer at all. A named reset (`reset at 2026-10-12 02:02:35`,
+    read as local time) or a `retry-after-ms` wins; else `default` from now. A
+    reset further than HEALTH_DOWN_MAX away is capped: a wrong year must not lock a
+    family out for good."""
+    import time
+    now = time.time() if now is None else now
+    text = str(text or "")
+    if not _LIMITED.search(text):
+        return None
+    until = None
+    hit = _RESET_AT.search(text)
+    if hit:
+        try:
+            until = time.mktime(time.strptime("%s %s" % hit.groups(), "%Y-%m-%d %H:%M:%S"))
+        except (ValueError, OverflowError):
+            until = None
+        if until is not None and until <= now:
+            # a named reset already past is a clock we misread (the provider's
+            # zone is not stated): a minute's hold would re-probe every prompt
+            until = now + default
+    if until is None:
+        ms = _RETRY_MS.search(text)
+        until = now + int(ms.group(1)) / 1000.0 if ms else now + default
+    return min(max(until, now + 60), now + HEALTH_DOWN_MAX)
+
+
+@contextlib.contextmanager
+def _health_locked():
+    """An exclusive flock on the record's lock file around one re-read, change
+    and write, so two writers (a slice's stop, the probe) do not drop each
+    other's hold. Unlocked where fcntl is missing or the file cannot be opened."""
+    fh = None
+    try:
+        import fcntl
+        os.makedirs(os.path.dirname(_health_path()), exist_ok=True)
+        fh = open(_health_path() + ".lock", "a", encoding="utf-8")
+        fcntl.flock(fh, fcntl.LOCK_EX)
+    except (ImportError, OSError):
+        pass
+    try:
+        yield
+    finally:
+        if fh is not None:
+            fh.close()
+
+
+def _family(provider="", model="", default=""):
+    """The OMP_FAMILIES entry a provider id (omp's auth-store id), else a model id
+    (`_vendor`), else `default` runs under; None when none is one."""
+    by_provider = {auth[0]: family for family, auth in OMP_AUTH.items()}
+    for family in (by_provider.get(str(provider or "").lower()),
+                   _vendor(str(model)) if model else None, default):
+        if family in OMP_FAMILIES:
+            return family
+    return None
+
+
+def note_limit(text, provider="", model="", transient=False, default="", now=None):
+    """Hold down the family a slice stopped on with a limit answer (`text`), and
+    re-apply omp's chain, so the next spawn of this session leaves that family
+    instead of the next session start's probe moving it (research
+    orchestrator-flow-audit S2, F3a). A rate limit (`transient`) with no reset
+    named holds HEALTH_RATE, a quota HEALTH_DOWN. Returns the family newly held,
+    else None: no family resolves (`_family`), `text` is no limit answer
+    (`limit_until`), the family is already held, or TEZGAH_HEALTH_CHECK=0 (the
+    suite's switch)."""
+    import time
+    family = _family(provider, model, default)
+    if not family or os.environ.get("TEZGAH_HEALTH_CHECK") == "0":
+        return None
+    now = time.time() if now is None else now
+    until = limit_until(text, now, HEALTH_RATE if transient else HEALTH_DOWN)
+    if until is None:
+        return None
+    with _health_locked():
+        data = read_health()
+        if family in down_families(now, data):
+            return None
+        data["down"][family] = {"until": until,
+                                "reason": " ".join(str(text).split())[:200]}
+        if not write_health(data):
+            return None
+    apply_omp()
+    return family
+
+
+def other_family_up(text):
+    """Where work a limit stopped on can move: the first family the routing lets
+    a chain fall back to (`_chain` under `tp.fallback_policy()`, every slot) that
+    is funded and not down (`funded_families`) and that `text` does not name
+    (`named_families`), else None. None with routing off or under
+    TEZGAH_HEALTH_CHECK=0, so the suite never reads this machine's credentials."""
+    if os.environ.get("TEZGAH_HEALTH_CHECK") == "0":
+        return None
+    mode = omp_mode()
+    if mode not in OMP_FAMILIES:
+        return None
+    funded = funded_families(live=True)
+    chained = {sel for slot in SLOTS for sel in _chain(mode, slot, funded)}
+    named = named_families(text)
+    return next((family for family in funded if family not in named and any(
+        sel.startswith(OMP_AUTH[family][0] + "/") for sel in chained)), None)
+
+
+def named_families(text):
+    """The OMP_FAMILIES `text` names by an auth-store provider id (a whole word)
+    or a model stem (`VENDOR_STEMS`, a word start): `openrouter 403` names `any`,
+    `glm-5.3` names `zai`."""
+    low = str(text or "").lower()
+    return {family for family in OMP_FAMILIES
+            if re.search(r"\b%s\b" % re.escape(OMP_AUTH[family][0]), low)
+            or any(re.search(r"\b%s" % re.escape(s), low)
+                   for s, v in VENDOR_STEMS if v == family)}
+
+
+def _openrouter_key():
+    env, home = tp.PROVIDER_KEYS["openrouter"]
+    key = os.environ.get(env, "").strip()
+    if key:
+        return key
+    try:
+        with open(os.path.join(tp.HOME, home), encoding="utf-8") as fh:
+            return fh.read().strip()
+    except OSError:
+        return ""
+
+
+def probe_family(family, timeout=60):
+    """(up, reason) for one family: None for up when the probe could not tell.
+
+    `any` asks OpenRouter's key endpoint, which costs no tokens: a key whose
+    `limit_remaining` is 0 or less is down. A family omp runs is asked one short
+    prompt on that family's cheap row through `omp -p --no-session`; exit 0 is
+    up, a limit answer is down (its reset in `reason`), anything else is unknown."""
+    if family == "any":
+        key = _openrouter_key()
+        if not key:
+            return None, "no OpenRouter key"
+        req = urllib.request.Request(OPENROUTER_KEY,
+                                     headers={"Authorization": "Bearer " + key})
+        try:
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                info = (json.loads(resp.read().decode("utf-8")) or {}).get("data") or {}
+        except Exception as exc:  # noqa: BLE001 - any network failure is "cannot tell"
+            text = str(exc)
+            return (False, text) if _LIMITED.search(text) else (None, text)
+        left = info.get("limit_remaining")
+        if isinstance(left, (int, float)) and left <= 0:
+            return False, "OpenRouter key limit exhausted (limit %s, usage %s)" % (
+                info.get("limit"), info.get("usage"))
+        return True, "OpenRouter key has room"
+    exe = tp.omp_bin()
+    if not exe:
+        return None, "omp not found"
+    # TEZGAH_NESTED, as consult and the judge set it: a hook that does load in
+    # the child records nothing and refuses nothing
+    env = dict(os.environ, PI_CODING_AGENT_DIR=OMP_AGENT, TEZGAH_NESTED="1")
+    try:
+        # the consult argv: no tools, rules, skills, extensions or title call, so
+        # the probe is one short request and fires no nested tezgah hooks
+        argv = [exe] + tp.CONSULT_CLIS["omp"][0][1:]
+        proc = subprocess.run(argv + ["--model", _selector(family, "cheap"),
+                                      "--max-time=%d" % timeout, "Reply with exactly: OK"],
+                              capture_output=True, text=True, timeout=timeout + 15,
+                              env=env, cwd=tp.HOME)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return None, str(exc)
+    text = (proc.stdout or "") + (proc.stderr or "")
+    if proc.returncode == 0:
+        return True, "answered"
+    tail = " ".join(text.split())[-200:]
+    return (False, tail) if _LIMITED.search(text) else (None, tail)
+
+
+def refresh_health(mode=None, probe=probe_family, now=None):
+    """Probe every family with a credential except the mode's own (it leads the
+    chain whatever its state, and the session is running on it), record the
+    downs with their resets, and return the record. A family the probe cannot
+    judge keeps the state it had. The probes run unlocked; their results land on
+    the record re-read under the lock (`_health_locked`), so a hold a slice's
+    stop wrote meanwhile stays."""
+    import time
+    now = time.time() if now is None else now
+    mode = mode or omp_mode()
+    seen = {family: probe(family) for family in funded_families(live=False)
+            if family != mode}
+    with _health_locked():
+        down = dict(read_health()["down"])
+        for family, (up, reason) in seen.items():
+            if up is True:
+                down.pop(family, None)
+            elif up is False:
+                down[family] = {"until": limit_until(reason, now) or now + HEALTH_DOWN,
+                                "reason": reason[:200]}
+        data = {"checked": now, "down": {f: r for f, r in down.items()
+                                         if isinstance(r, dict) and r.get("until", 0) > now}}
+        write_health(data)
+    return data
+
+
+def health_due(data=None, now=None):
+    """True when the record was never checked, is older than HEALTH_EVERY, or
+    holds a down family whose reset has passed since it was checked. Never with
+    TEZGAH_HEALTH_CHECK=0 (the test suite's switch, like TEZGAH_UPDATE_CHECK)."""
+    import time
+    if os.environ.get("TEZGAH_HEALTH_CHECK") == "0":
+        return False
+    now = time.time() if now is None else now
+    data = read_health() if data is None else data
+    checked = data.get("checked")
+    if not isinstance(checked, (int, float)) or now - checked >= HEALTH_EVERY:
+        return True
+    return any(isinstance(row, dict) and checked < row.get("until", 0) <= now
+               for row in data["down"].values())
+
+
+def start_health():
+    """Stamp the record, then start one detached `tezgah-route --health`, so the
+    session starts that follow read a fresh stamp and start nothing. False when
+    nothing started."""
+    import sys
+    import time
+    with _health_locked():
+        data = read_health()
+        data["checked"] = time.time()
+        if not write_health(data):
+            return False
+    route = os.path.join(os.path.dirname(os.path.dirname(os.path.realpath(__file__))),
+                         "bin", "tezgah-route")
+    kwargs = {"stdin": subprocess.DEVNULL, "stdout": subprocess.DEVNULL,
+              "stderr": subprocess.DEVNULL, "close_fds": True}
+    if os.name == "posix":
+        kwargs["start_new_session"] = True
+    else:  # pragma: no cover - Windows: no console, outlives its parent
+        kwargs["creationflags"] = 0x00000008 | 0x00000200
+    try:
+        subprocess.Popen([sys.executable, route, "--health"], **kwargs)
+        return True
+    except OSError:
+        return False
 
 
 def omp_mode(default_selector=None):
@@ -308,11 +622,14 @@ def _chain(mode, slot, funded, agent=""):
     because a session on Opus that ran its subagents on GPT and GLM after one
     Anthropic 429 is the failure the owner reported (2026-10-07). `none`: the
     mode's selector alone. `any`: every other funded family, each on that
-    slot's own row, rotated by the agent's own name (`agent`): identical chains
-    for every agent meant one family's 429 moved all of them onto the same next
-    family in the same moment, which is the cascade the chain exists to break
-    (independent review, 2026-10-01). The rotation is deterministic - the same
-    agent resolves the same order on every machine - so nothing here is random."""
+    slot's own row. The families omp runs on an account (zai) come before
+    OpenRouter, which bills per token - the owner's ask (2026-10-11) was to use
+    zai when it is up - and among those the order is rotated by the agent's own
+    name (`agent`): identical chains for every agent meant one family's 429
+    moved all of them onto the same next family in the same moment, which is the
+    cascade the chain exists to break (independent review, 2026-10-01). The
+    rotation is deterministic - the same agent resolves the same order on every
+    machine - so nothing here is random."""
     policy = tp.fallback_policy()
     families = [mode] + [f for f in OMP_FAMILIES if f != mode and f in funded]
     if policy == "none":
@@ -327,10 +644,11 @@ def _chain(mode, slot, funded, agent=""):
                 out.append("openrouter/" + OPENROUTER_ID[model]
                            + (":" + effort if effort else ""))
         return list(dict.fromkeys(out))
-    tail = families[1:]
+    tail = [f for f in families[1:] if f != "any"]
     if agent and len(tail) > 1:
         shift = sum(ord(c) for c in agent) % len(tail)
-        families = families[:1] + tail[shift:] + tail[:shift]
+        tail = tail[shift:] + tail[:shift]
+    families = families[:1] + tail + [f for f in families[1:] if f == "any"]
     return [_selector(family, slot) for family in families]
 
 
@@ -552,7 +870,11 @@ def apply_omp(remove=False):
     owns.update(owns_chains)
     merged_chains = dict(chains)
     for key in flat_chains:
-        role = key.split(".", 1)[1]
+        role = key.rsplit(".", 1)[1]
+        # an earlier release wrote the chain under `fallbackChains.<role>`, a key
+        # omp never reads (the `split(".", 1)` of the flat key); it is tezgah's
+        # own and goes
+        merged_chains.pop("fallbackChains." + role, None)
         value = new_chains.get(key)
         if value is None:
             merged_chains.pop(role, None)
@@ -863,40 +1185,84 @@ def _in_order(routes, kids):
     return [stem for _ts, stem in kids]
 
 
-def _join(routes, kids, spawned_as):
-    """[child stem or None] per route. A child's type is what its parent's task
-    call recorded for its name (`spawn` rows, omp), else its own `agent` (the
-    type itself on opencode). With every child typed, each route agent's routes
-    join that agent's children by `_in_order`, and a child of an unrouted type
-    is left out; with any child untyped, order over all of them is the only
-    evidence. Whatever is not proven stays None (`unjoined`)."""
-    typed = [(ts, stem, spawned_as.get(agent, agent)) for ts, stem, agent in kids]
-    if any(kind is None for _ts, _stem, kind in typed):
-        stems = _in_order(routes, [(ts, stem) for ts, stem, _k in typed])
-        return stems or [None] * len(routes)
-    out = [None] * len(routes)
+# How far apart, in seconds, two children of one task call start: an omp call
+# of 11 workers opened their ledgers over 2 seconds (ledger 01a12277). A second
+# task call within that gap would read as part of the first - ponytail: a model
+# turn between two calls takes longer than this.
+FAN_OUT_GAP = 2
+
+# How long after its route a route's first worker may start: tezgah-route runs
+# right before the task call. The joined omp routes (ledgers 01a12277, 01a12bf1)
+# started theirs 39 to 1296 s later; 1296 s is a route made beside another and
+# run after it finished. Past this a same-type child proves nothing.
+ROUTE_GAP = 1800
+
+
+def _fan_out(kids):
+    """The children of the first task call in sorted [(ts, key)]: each started
+    within FAN_OUT_GAP of the one before."""
+    out = kids[:1]
+    for kid in kids[1:]:
+        if kid[0] - out[-1][0] > FAN_OUT_GAP:
+            break
+        out.append(kid)
+    return out
+
+
+def _join(routes, kids):
+    """[[child key]] per route, [] where unjoined; `kids` is [(ts, key, type)],
+    type None when no row typed the child.
+
+    With no child typed, order over all of them is the only evidence
+    (`_in_order`). Otherwise each route agent's routes join that agent's
+    children: a route owns the first fan-out of its type after it and before
+    the next route of its type - later same-type spawns are ones no route sent.
+    It owns nothing when the route before it of its type had no worker yet
+    (both routes' workers may be in this one fan-out), when the fan-out started
+    more than ROUTE_GAP after it, or when an untyped child started inside its
+    span (that child could be its worker). A child of an
+    unrouted type is left out. Whatever is not proven stays unjoined."""
+    if kids and all(kind is None for _ts, _key, kind in kids):
+        keys = _in_order(routes, [(ts, key) for ts, key, _k in kids])
+        return [[key] for key in keys] if keys else [[] for _r in routes]
+    out = [[] for _r in routes]
+    untyped = [ts for ts, _key, kind in kids if kind is None]
     for agent in {fields.get("agent") for _ts, fields in routes}:
         mine = [i for i, (_ts, fields) in enumerate(routes) if fields.get("agent") == agent]
-        stems = _in_order([routes[i] for i in mine],
-                          [(ts, stem) for ts, stem, kind in typed if kind == agent])
-        for i, stem in zip(mine, stems or []):
-            out[i] = stem
+        theirs = sorted((ts, key) for ts, key, kind in kids if kind == agent)
+        for n, i in enumerate(mine):
+            start = routes[i][0]
+            end = routes[mine[n + 1]][0] if n + 1 < len(mine) else float("inf")
+            if n and not any(routes[mine[n - 1]][0] <= ts < start for ts, _key in theirs):
+                continue
+            batch = _fan_out([kid for kid in theirs if start <= kid[0] < end])
+            if batch and batch[0][0] - start <= ROUTE_GAP \
+                    and not any(start <= ts <= batch[-1][0] for ts in untyped):
+                out[i] = [key for _ts, key in batch]
     return out
 
 
+# A fan-out's outcome is its most telling first check: one failed worker fails
+# the route, so a fan-out never hides a failure behind a sibling's pass.
+OUTCOME_ORDER = ("fail", "pass", "ran", "none")
+
+
 def route_report(ledgers):
     """({(via, tier): counts}, counts for Jev routes below the static tier) over
     {ledger stem: rows}.
 
-    A routed worker runs in its own session, so its checks are in its own ledger,
-    whose `spawned` row names the parent session the route row was written under.
-    A route joins the child `_join` can prove is its worker, and the outcome is
-    that child's first check (`pass`, `fail`, `ran`, `none`). A route it cannot
-    prove - an unrouted spawn, a tie, a host that writes no `spawned` row - is
-    `unjoined`: the parent's own next check is never taken for the worker's, and
-    neither is a guess. The second count is the V2-as-default question: Jev
-    picking under the static table's tier, and how often that first attempt
-    failed (docs/models.md)."""
+    A routed worker on omp and opencode runs in its own session, so its checks
+    are in its own ledger, whose `spawned` row names the parent session the
+    route row was written under. On Claude and Codex it runs under its parent's
+    session id: its rows are in the parent's ledger with `agent` = its id, and
+    the `subagent_start` row (SubagentStart's agent_id, agent_type in `detail`)
+    types it. A route joins the children `_join` can prove are its workers, and
+    the outcome is their first check (`pass`, `fail`, `ran`, `none`; over a
+    fan-out, OUTCOME_ORDER's first). A route it cannot prove - an unrouted
+    spawn, a tie, a host that writes no child row - is `unjoined`: the parent's
+    own next check is never taken for the worker's, and neither is a guess. The
+    second count is the V2-as-default question: Jev picking under the static
+    table's tier, and how often that first attempt failed (docs/models.md)."""
     def counts():
         return {"routes": 0, "pass": 0, "fail": 0, "ran": 0, "none": 0, "unjoined": 0}
     def spawn_rows(rows):
@@ -906,7 +1272,11 @@ def route_report(ledgers):
     for stem, rows in ledgers.items():
         link = next((r for r in rows if r.get("kind") == "spawned" and r.get("parent")),
                     None)
-        if link:
+        # Cursor's row is written from the parent's subagentStart under the
+        # child's `subagent_id`; that the child's own calls carry this id is not
+        # documented, so the link counts only once a row of the child's landed
+        if link and not (link.get("host") == "cursor"
+                         and all(r.get("kind") == "spawned" for r in rows)):
             children.setdefault(ti._slug(link["parent"]), []).append(
                 (link.get("ts") or 0, stem, link.get("agent")))
     groups, below = {}, counts()
@@ -918,15 +1288,27 @@ def route_report(ledgers):
         # orchestrator shares the parent's TEZGAH_SESSION, so its worker names
         # that parent while the row typing the worker is in the orchestrator's
         # ledger. Another session's task names never type this one's children.
-        # A name two calls typed differently is untyped (None): order decides.
+        # A name two calls typed differently is untyped (None).
         spawned_as = {}
         for r in spawn_rows(rows) + [r for _ts, kid, _a in children.get(stem, [])
                                      for r in spawn_rows(ledgers[kid])]:
             if spawned_as.setdefault(r["child"], r["agent"]) != r["agent"]:
                 spawned_as[r["child"]] = None
-        for (_ts, fields), kid in zip(routes, _join(routes, children.get(stem, []),
-                                                    spawned_as)):
-            outcome = _outcome(ledgers[kid]) if kid else "unjoined"
+        # a child key is (ledger stem, agent id): "" for a whole ledger; an
+        # empty type (a Cursor subagentStart with no subagent_type) is no type
+        kids = [(ts, (kid, ""), spawned_as.get(name, name) or None)
+                for ts, kid, name in children.get(stem, [])]
+        # a Claude plugin agent's type is plugin-scoped (`tezgah:tezgah-cheap`)
+        kids += [(r.get("ts") or 0, (stem, r["agent"]),
+                  str(r.get("detail") or "").rsplit(":", 1)[-1] or None)
+                 for r in rows if r.get("kind") == "subagent_start"
+                 and isinstance(r.get("agent"), str) and r["agent"]]
+        for (_ts, fields), keys in zip(routes, _join(routes, kids)):
+            got = {_outcome(ledgers[kid] if not agent else
+                            [r for r in ledgers[kid] if r.get("agent") == agent
+                             and r.get("kind") != "subagent_start"])
+                   for kid, agent in keys}
+            outcome = next((o for o in OUTCOME_ORDER if o in got), "unjoined")
             bins = [groups.setdefault((fields["via"], fields["tier"]), counts())]
             static = fields.get("static")
             if fields["via"] == "jev" and static in TIERS and \