From 2ac82cad082f5d55fa0cd687cde26a1e7edc1210 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Sun, 25 Oct 2026 12:36:33 -0700
Subject: [PATCH 1/8] fix(adapters): pause a Claude session blocked by a usage
 limit instead of charging it (#610)

A Claude Code session stopped behind a subscription limit idled out its
clock and was charged a dev attempt, eventually deferring a story whose
spec was fine. Seeding the captured lines as env-fault patterns alone
would not have helped: #764's token veto overrules any post-mortem match
on a session that billed tokens before it hit the wall, which is every
such session.

Add the usage-limit pattern class: profile fields usage_limit_patterns
(blocked, no auto-continue: credit exhaustion) and usage_wait_patterns
(blocked until a reset the CLI continues from), disjoint by contract,
seeded in claude.toml from the lines captured in #610's runs. The wait
loop matches them against the VISIBLE pane at stall-grace expiry (one
capture shared with the parked gate; the nudge is withheld and the
session ends stalled + parked) and once when the session timeout fires.
A dead window is never usage-limited.

A live sighting sets SessionResult.usage_limited, and only that is
exempt from the token veto: the line is on screen at the verdict, so
tokens spent before the limit cannot disprove it. The same patterns
also scan the log tail as ordinary env-fault families, where the veto
still applies, so a session that recovered from a limit and later
stalled for a real reason is still charged. Both pause reasons name a
usage limit when the field is set; session-end and workflow-end carry
it present-only. The corpus gates now cover all three pane fields.

Co-authored-by: sirendhead <dongpt@customthing.net>
---
 CHANGELOG.md                            |   5 +
 src/bmad_loop/adapters/base.py          |   9 +
 src/bmad_loop/adapters/env_fault.py     |  63 ++++-
 src/bmad_loop/adapters/generic.py       | 160 +++++++-----
 src/bmad_loop/adapters/profile.py       |  29 +++
 src/bmad_loop/data/profiles/claude.toml |  46 +++-
 src/bmad_loop/engine.py                 |   7 +
 src/bmad_loop/escalation.py             |  29 ++-
 tests/test_engine.py                    |  49 ++++
 tests/test_env_fault.py                 |   2 +
 tests/test_env_fault_patterns.py        | 312 ++++++++++++++++++------
 tests/test_escalation.py                |  52 ++++
 tests/test_generic_tmux.py              | 284 ++++++++++++++++++++-
 tests/test_portability_guard.py         |   5 +
 tests/test_profile.py                   | 138 ++++++++++-
 15 files changed, 1038 insertions(+), 152 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 67ffb8016..7b0294f20 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -175,6 +175,11 @@ breaking changes may land in a minor release.
 
 ### Fixed
 
+- Pause a Claude session blocked by a usage limit (credit exhaustion or a session-window
+  limit seen on the live pane) with a `usage limit:` reason instead of charging it a dev
+  attempt; a live sighting is exempt from the token veto. New profile fields
+  `usage_limit_patterns` and `usage_wait_patterns`, seeded from lines captured in
+  community reports (#610).
 - Read an epic the initiative declares but has not sliced yet: `status` no longer
   faults the board on its folderless row, and it triggers no retrospective or closure.
 - Name the T1 ticket plan an interrupted commit window left `done` or `blocked` when
diff --git a/src/bmad_loop/adapters/base.py b/src/bmad_loop/adapters/base.py
index 9bdfa3fba..ac4eba07d 100644
--- a/src/bmad_loop/adapters/base.py
+++ b/src/bmad_loop/adapters/base.py
@@ -343,6 +343,15 @@ class SessionResult:
     # in `session_failure_reason`. Diagnostic only: never read by routing.
     # APPENDED.
     env_fault_overruled: str | None = None
+    # Usage-limit evidence (#610): the visible-pane line a `usage_limit_patterns`
+    # / `usage_wait_patterns` match found LIVE — at stall-grace expiry (ending
+    # the session stalled + parked) or the instant the session timeout fired.
+    # Set only from a live pane sighting, never from the post-mortem log tail and
+    # never on a `crashed` or completed result. A set value makes
+    # `_classify_env_fault` stamp `env_fault` WITHOUT the #764 token veto (the
+    # limit is on screen now, not a stale match), and both pause reasons name it
+    # as a usage limit. APPENDED.
+    usage_limited: str | None = None
 
 
 class CodingCLIAdapter(ABC):
diff --git a/src/bmad_loop/adapters/env_fault.py b/src/bmad_loop/adapters/env_fault.py
index 455acd375..25011a06d 100644
--- a/src/bmad_loop/adapters/env_fault.py
+++ b/src/bmad_loop/adapters/env_fault.py
@@ -47,6 +47,14 @@
 rationale that already excludes ``over_budget``. Untracked usage (``None``), a
 tracked zero, or a fault reading usage keep today's verdict: only a measurement
 can overrule.
+
+A usage-limit line the wait loop saw LIVE on the visible pane (#610,
+``SessionResult.usage_limited``) is the one verdict the veto does not touch: a
+session that billed tokens and then hit its subscription limit is exactly the
+case the limit pause exists for, and the sighting is of the screen as it stood,
+not a stale line from earlier in the log. The same usage patterns also scan the
+log TAIL as ordinary families, and there the veto applies — a limit the session
+recovered from must not excuse a later real stall.
 """
 
 from __future__ import annotations
@@ -112,7 +120,8 @@ class EnvFaultMixin:
     Mixed into every adapter that writes a per-task diagnostic log; which files
     are scanned is named by ``ENV_FAULT_LOG_SUFFIXES`` (or, when that is unset,
     the single ``ENV_FAULT_LOG_SUFFIX``). Inert for a profile with no
-    ``env_fault_patterns``, so mixing it in is always safe.
+    ``env_fault_patterns`` and no usage-limit patterns (and no live
+    ``usage_limited`` sighting), so mixing it in is always safe.
 
     Several files are scanned independently — each its own tail, straddle and
     match-timeout handling, each read fault its own crumb — and the last match
@@ -190,6 +199,26 @@ def _env_fault_patterns(self) -> tuple[regex.Pattern[str], ...]:
         ``_env_fault_patterns`` directly instead."""
         return tuple(regex.compile(p) for p in self.profile.env_fault_patterns)
 
+    @cached_property
+    def _usage_limit_patterns(self) -> tuple[regex.Pattern[str], ...]:
+        """``profile.usage_limit_patterns``, compiled once per adapter (#610).
+        Validated at parse time with this engine, so compiling cannot raise. Same
+        caching CONSTRAINT as ``_env_fault_patterns``. Read by the live pane gates
+        (generic.py) and, as ordinary families, by the log-tail scan here."""
+        return tuple(regex.compile(p) for p in self.profile.usage_limit_patterns)
+
+    @cached_property
+    def _usage_wait_patterns(self) -> tuple[regex.Pattern[str], ...]:
+        """``profile.usage_wait_patterns``, compiled once per adapter (#610); as
+        ``_usage_limit_patterns``."""
+        return tuple(regex.compile(p) for p in self.profile.usage_wait_patterns)
+
+    @property
+    def _tail_scan_patterns(self) -> tuple[regex.Pattern[str], ...]:
+        """Every family the post-mortem tail scan matches: the env-fault patterns,
+        then both usage-limit lists as ordinary families (subject to the veto)."""
+        return self._env_fault_patterns + self._usage_limit_patterns + self._usage_wait_patterns
+
     def _classify_env_fault(
         self, handle: SessionHandle, spec: SessionSpec, result: SessionResult
     ) -> SessionResult:
@@ -208,12 +237,30 @@ def _classify_env_fault(
         ``env_fault`` stays False, ``env_fault_overruled`` carries the evidence,
         and an ``env-fault-overruled`` breadcrumb (with ``tokens``) replaces the
         classified one. Usage is read only after a match, so a healthy log costs
-        no extra read."""
-        if (
-            not self._env_fault_patterns
-            or result.status not in ENV_FAULT_STATUSES
-            or result.result_json is not None
-        ):
+        no extra read. The tail scan covers ``env_fault_patterns`` and both usage
+        lists (``_tail_scan_patterns``); a tail-only usage match is overruled
+        like any other.
+
+        A LIVE usage-limit sighting (``result.usage_limited``, #610) short-cuts
+        all of that: ``env_fault`` is stamped with that evidence and no veto and
+        no tail scan, crumbed ``env-fault-classified`` with
+        ``usage_limited=True``."""
+        if result.status not in ENV_FAULT_STATUSES or result.result_json is not None:
+            return result
+        if result.usage_limited is not None:
+            # Veto-exempt by design: the line was on the visible pane at the
+            # verdict, so tokens spent BEFORE the limit cannot disprove it.
+            self._note_lifecycle(
+                handle.task_id,
+                "env-fault-classified",
+                status=result.status,
+                evidence=result.usage_limited,
+                usage_limited=True,
+            )
+            return dataclasses.replace(
+                result, env_fault=True, env_fault_evidence=result.usage_limited
+            )
+        if not self._tail_scan_patterns:
             return result
         evidence = self._env_fault_evidence(handle.task_id)
         if evidence is None:
@@ -287,7 +334,7 @@ def _env_fault_evidence(self, task_id: str) -> str | None:
             if lines is None:
                 continue  # read fault, crumbed: the other files still count
             for line in lines:
-                for pat in self._env_fault_patterns:
+                for pat in self._tail_scan_patterns:
                     try:
                         hit = pat.search(line, timeout=ENV_FAULT_MATCH_TIMEOUT_S)
                     except TimeoutError as exc:
diff --git a/src/bmad_loop/adapters/generic.py b/src/bmad_loop/adapters/generic.py
index 0893e273c..1c991f8b5 100644
--- a/src/bmad_loop/adapters/generic.py
+++ b/src/bmad_loop/adapters/generic.py
@@ -1430,6 +1430,44 @@ def produced_work() -> bool:
                 handle, stop_seen, activity_seen or transcript_work_seen or usage_seen
             )
 
+        def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
+            """The non-completion exit of a stalled session (DW-348, #610):
+            resolve, then re-probe liveness. A now-dead window is ``crashed``
+            (never parked or usage-limited: nothing waits on a human once the CLI
+            is gone). Otherwise ``stalled`` with ``accept_result=False``: an
+            artifact on disk cannot upgrade the stall to completed (it may be
+            stale or mid-write; only a Stop or window death vouches for it), and
+            ``parked_now`` / ``usage_now`` label it. Both exits carry the
+            rollout."""
+            try_resolve()
+            if self._probe_liveness(handle, "stall") is False:
+                return self._final(
+                    handle,
+                    spec,
+                    "crashed",
+                    session_id,
+                    transcript_path,
+                    budget_weighted=budget_weighted,
+                    stop_seen=stop_seen,
+                    produced_work=produced_work(),
+                )
+            stalled = self._final(
+                handle,
+                spec,
+                "stalled",
+                session_id,
+                transcript_path,
+                accept_result=False,
+                budget_weighted=budget_weighted,
+                stop_seen=stop_seen,
+                produced_work=produced_work(),
+            )
+            if parked_now is not None:
+                return dataclasses.replace(
+                    stalled, parked=True, parked_evidence=parked_now, usage_limited=usage_now
+                )
+            return stalled
+
         while True:
             # Top-of-tick pane-frame sample for the no-work verdict (#727). Before
             # the timeout check so growth on the final tick still counts; before the
@@ -1463,6 +1501,15 @@ def produced_work() -> bool:
                 # rollout existed, then no further hook event): the exit's
                 # `transcript_path` argument is read before `produced_work()`.
                 try_resolve()
+                # One look at the visible pane for a usage limit (#610): a
+                # session whose clock ran out while it sat behind one is not a
+                # failed attempt. A dead window is never usage-limited (the CLI
+                # is gone, though a remain-on-exit pane still captures), so a
+                # match is confirmed alive first; a probe fault reads "not dead".
+                (usage_hit,) = self._pane_evidence(handle, self._usage_pane_patterns)
+                usage_now = None
+                if usage_hit is not None and self._probe_liveness(handle, "timeout") is not False:
+                    usage_now = usage_hit[0]
                 return SessionResult(
                     status="timeout",
                     session_id=session_id,
@@ -1472,6 +1519,7 @@ def produced_work() -> bool:
                     budget_weighted=budget_weighted,
                     stop_seen=stop_seen,
                     produced_work=produced_work(),
+                    usage_limited=usage_now,
                 )
             # Hard-stop poll (#319), per-iteration and deliberately NOT inside
             # the heartbeat throttle below: the loop's own wait is capped at 5s
@@ -1787,15 +1835,30 @@ def produced_work() -> bool:
                     # (nudges spent, or none configured) is labelled parked too
                     # and pauses instead of retrying (DW-433). Either way no
                     # nudge is typed and the session ends through the tail below.
+                    # The same single capture is matched against the usage-limit
+                    # lists (#610): a CLI stopped behind a usage limit is parked
+                    # too (a nudge can only reproduce the limit line), and the
+                    # match is recorded as `usage_limited` even when the hook
+                    # latch already supplied the parked evidence, since claude's
+                    # idle_prompt latches on exactly this kind of idle.
                     parked_now = parked_evidence
+                    parked_hit, usage_hit = self._pane_evidence(
+                        handle,
+                        self._parked_prompt_patterns if parked_now is None else (),
+                        self._usage_pane_patterns,
+                    )
+                    if parked_now is None and parked_hit is not None:
+                        parked_now = parked_hit[0]
+                    usage_now = usage_hit[0] if usage_hit is not None else None
                     if parked_now is None:
-                        parked_now = self._pane_parked_evidence(handle)
+                        parked_now = usage_now
                     if parked_now is not None:
                         self._note_lifecycle(
                             handle.task_id,
                             "stall-nudge-withheld",
                             evidence=parked_now,
                             nudge_due=nudge_due,
+                            **({"usage_limited": usage_now} if usage_now is not None else {}),
                         )
                     elif nudge_due:
                         # The wake nudge IS the re-invocation bmad-loop otherwise
@@ -1830,36 +1893,7 @@ def produced_work() -> bool:
                     # persistent failure. A dead window is never labelled parked:
                     # nothing is waiting on a human once the CLI is gone. The
                     # probe fault is crumbed (`site="stall"`, DW-454).
-                    # Both exits below (crashed or stalled) carry the rollout.
-                    try_resolve()
-                    if self._probe_liveness(handle, "stall") is False:
-                        return self._final(
-                            handle,
-                            spec,
-                            "crashed",
-                            session_id,
-                            transcript_path,
-                            budget_weighted=budget_weighted,
-                            stop_seen=stop_seen,
-                            produced_work=produced_work(),
-                        )
-                    # Still alive: an artifact on disk cannot upgrade the stall to
-                    # completed — it may be stale or mid-write; only a Stop or
-                    # window death vouches for it.
-                    stalled = self._final(
-                        handle,
-                        spec,
-                        "stalled",
-                        session_id,
-                        transcript_path,
-                        accept_result=False,
-                        budget_weighted=budget_weighted,
-                        stop_seen=stop_seen,
-                        produced_work=produced_work(),
-                    )
-                    if parked_now is not None:
-                        return dataclasses.replace(stalled, parked=True, parked_evidence=parked_now)
-                    return stalled
+                    return stall_exit(parked_now, usage_now)
                 continue
             # Drop a nested CLI's events before they can re-point the identity
             # or transcript, set stop_seen, spend nudges or re-arm the stall
@@ -2401,28 +2435,32 @@ def _parked_prompt_patterns(self) -> tuple[regex.Pattern[str], ...]:
         first stall-expiry, or assign this attribute directly."""
         return tuple(regex.compile(p) for p in self.profile.parked_prompt_patterns)
 
-    def _pane_parked_evidence(self, handle: SessionHandle) -> str | None:
-        """Whether the VISIBLE pane shows a prompt only a human should answer
-        (DW-350): the evidence (pattern plus quoted line) of the first
-        ``parked_prompt_patterns`` match, else None.
-
-        Read only at a stall-grace expiry with no hook latch — whether a wake
-        nudge is due or the stall is final (DW-433). Observation that
-        degrades: no patterns, a backend that cannot capture (the seam default
-        raises ``MultiplexerError``; a duck-typed backend may lack the method),
-        a capture fault, or a search that blows ``PARKED_PROMPT_MATCH_TIMEOUT_S``
-        all read as "no match": a due nudge goes out, or the final stall ends
-        unparked, exactly as before. The two faults are not silent (DW-448): a
+    def _pane_evidence(
+        self, handle: SessionHandle, *pattern_sets: tuple[regex.Pattern[str], ...]
+    ) -> tuple[tuple[str, str] | None, ...]:
+        """One look at the VISIBLE pane, matched against each pattern set: per
+        set, ``(evidence, matched_line)`` for its first match (lines outer,
+        patterns inner; evidence = pattern plus quoted line), else None.
+
+        The shared matcher behind the parked gate (DW-350:
+        ``parked_prompt_patterns``) and the usage-limit gates (#610:
+        ``usage_limit_patterns`` + ``usage_wait_patterns``), so a decision point
+        that consults several sets captures the pane ONCE. Observation that
+        degrades: every set empty, or a backend that cannot capture (the seam
+        default raises ``MultiplexerError``; a duck-typed backend may lack the
+        method), reads as "no match" for every set; a capture fault does too;
+        a search that blows ``PARKED_PROMPT_MATCH_TIMEOUT_S`` reads as "no
+        match" for its own set. The two faults are not silent (DW-448): a
         ``parked-probe-failed`` crumb (``reason`` = ``capture-failed`` or
-        ``match-timeout`` + its ``pattern``; ``error``) records that the look
-        at the pane failed. No patterns and a backend without ``capture_pane``
-        are configuration, not faults, and stay silent."""
-        patterns = self._parked_prompt_patterns
-        if not patterns:
-            return None
+        ``match-timeout`` + its ``pattern``; ``error``) records that the look at
+        the pane failed. Empty sets and a backend without ``capture_pane`` are
+        configuration, not faults: no capture, no crumb."""
+        none: tuple[tuple[str, str] | None, ...] = tuple(None for _ in pattern_sets)
+        if not any(pattern_sets):
+            return none
         capture = getattr(self.mux, "capture_pane", None)
         if capture is None:
-            return None
+            return none
         try:
             screen = capture(handle.pane_target or handle.native_id)
         except MultiplexerError as e:
@@ -2432,11 +2470,17 @@ def _pane_parked_evidence(self, handle: SessionHandle) -> str | None:
                 reason="capture-failed",
                 error=f"{type(e).__name__}: {e}",
             )
-            return None
+            return none
         if not isinstance(screen, str):
-            return None
-        text = _ANSI_RE.sub("", screen.replace("\r", "\n"))
-        for line in text.split("\n"):
+            return none
+        lines = _ANSI_RE.sub("", screen.replace("\r", "\n")).split("\n")
+        return tuple(self._first_pane_match(handle, lines, pats) for pats in pattern_sets)
+
+    def _first_pane_match(
+        self, handle: SessionHandle, lines: list[str], patterns: tuple[regex.Pattern[str], ...]
+    ) -> tuple[str, str] | None:
+        """``_pane_evidence``'s search of one pattern set over captured lines."""
+        for line in lines:
             for pat in patterns:
                 try:
                     hit = pat.search(line, timeout=PARKED_PROMPT_MATCH_TIMEOUT_S)
@@ -2450,9 +2494,15 @@ def _pane_parked_evidence(self, handle: SessionHandle) -> str | None:
                     )
                     return None
                 if hit is not None:
-                    return f"pane matched {pat.pattern!r}: {_excerpt(line, hit.start())}"
+                    return (f"pane matched {pat.pattern!r}: {_excerpt(line, hit.start())}", line)
         return None
 
+    @property
+    def _usage_pane_patterns(self) -> tuple[regex.Pattern[str], ...]:
+        """Both usage-limit lists (#610) as the live gates consult them: disjoint
+        by contract, so either one matching means usage-limited."""
+        return self._usage_limit_patterns + self._usage_wait_patterns
+
     def _session_vanished(self, task_id: str) -> bool:
         # The disambiguating probe (#489): `list_window_ids` returns [] for a
         # dead window AND for a session that no longer exists, so a plain
diff --git a/src/bmad_loop/adapters/profile.py b/src/bmad_loop/adapters/profile.py
index 0024b1e6d..b6a92af53 100644
--- a/src/bmad_loop/adapters/profile.py
+++ b/src/bmad_loop/adapters/profile.py
@@ -265,6 +265,26 @@ class CLIProfile:
     # derive from usage_parser (SUBAGENT_TRANSCRIPT_DIR_DEFAULTS); "" = off.
     # APPENDED after session_id_flag for the same positional-compatibility reason.
     subagent_transcript_dir: str | None = None
+    # Patterns naming a subscription/usage limit the CLI is stopped behind (#610),
+    # matched line-by-line against the ANSI-stripped VISIBLE pane at the same live
+    # decision points as parked_prompt_patterns (stall-grace expiry, and once when
+    # the session timeout fires) and, as ordinary env-fault families, against the
+    # post-mortem log tail. Two lists, disjoint by contract — "usage-limited" means
+    # either one matched:
+    #   usage_limit_patterns: the CLI is BLOCKED and will not continue by itself
+    #     (credit exhaustion); pause now, an operator must act.
+    #   usage_wait_patterns: the CLI is blocked but WAITING for a reset it then
+    #     continues from on its own (a session-window limit).
+    # A LIVE pane sighting exempts the verdict from the #764 token veto (the line is
+    # on screen now, so it is not a stale match from earlier in the session); a
+    # tail-only match is still subject to it. Same evidentiary bar as
+    # env_fault_patterns: seed only lines captured from the CLI's own screen, with
+    # the run cited, and single-character classes so the profile line does not
+    # match itself. Compiled and validated at parse time; empty = inert.
+    # APPENDED after subagent_transcript_dir for the same positional-compatibility
+    # reason.
+    usage_limit_patterns: tuple[str, ...] = ()
+    usage_wait_patterns: tuple[str, ...] = ()
 
     @property
     def hookless(self) -> bool:
@@ -583,6 +603,13 @@ def fail(msg: str) -> ProfileError:
                 f"parked_prompt_patterns entry is not a valid regex: {pattern!r} ({e})"
             ) from e
 
+    for field_name in ("usage_limit_patterns", "usage_wait_patterns"):
+        for pattern in getattr(profile, field_name):
+            try:
+                regex.compile(pattern)  # same engine the usage gate matches with (timeout-guarded)
+            except (regex.error, RecursionError) as e:
+                raise fail(f"{field_name} entry is not a valid regex: {pattern!r} ({e})") from e
+
 
 def _legacy_adapter_default(dialect: str) -> str:
     """The adapter kind a TOML profile that predates the ``adapter`` field meant.
@@ -713,6 +740,8 @@ def str_list(key: str) -> tuple[str, ...]:
         seed_files=str_list("seed_files"),
         env_fault_patterns=str_list("env_fault_patterns"),
         parked_prompt_patterns=str_list("parked_prompt_patterns"),
+        usage_limit_patterns=str_list("usage_limit_patterns"),
+        usage_wait_patterns=str_list("usage_wait_patterns"),
         workspace_trust=workspace_trust,
         subagent_transcript_dir=raw_subagent_dir,
     )
diff --git a/src/bmad_loop/data/profiles/claude.toml b/src/bmad_loop/data/profiles/claude.toml
index 5396967f5..12570eb1c 100644
--- a/src/bmad_loop/data/profiles/claude.toml
+++ b/src/bmad_loop/data/profiles/claude.toml
@@ -55,10 +55,13 @@ seed_files = [
 # configuration as a provider outage (#507). Pinned by
 # test_shipped_patterns_do_not_match_their_own_profile_line.
 #
-# No usage-limit / quota cause is seeded: no captured Claude Code quota line
-# exists, and on a pane capture that vocabulary is what a story IMPLEMENTING
-# rate limiting prints all day. Seed one only from a captured line, citing the
-# run it came from — the bar test_unseeded_profiles_stay_inert states.
+# No usage-limit / quota cause is seeded HERE: on a pane capture that vocabulary
+# is what a story IMPLEMENTING rate limiting prints all day. The two captured
+# Claude Code usage-limit sentences live in their own class below
+# (usage_limit_patterns / usage_wait_patterns), which is looked at on the live
+# pane and is exempt from the token veto only there. Seed any further one only
+# from a captured line, citing the run it came from — the bar
+# test_unseeded_profiles_stay_inert states.
 #
 # To disable or extend, copy this profile into .bmad-loop/profiles/ and edit.
 env_fault_patterns = [
@@ -88,6 +91,41 @@ parked_prompt_patterns = [
   "Enter to confirm · Esc t[o] cancel",
 ]
 
+# Usage-limit patterns (#610): regexes matched line-by-line against the
+# ANSI-stripped VISIBLE pane at stall-grace expiry and when the session timeout
+# fires. A live match withholds the stall nudge and ends the session parked with
+# a usage-limit pause reason, exempt from the token veto (the line is on screen
+# now); the same patterns also scan the post-mortem log tail as ordinary
+# env-fault families, where the veto still applies (a limit the session
+# recovered from must not excuse a later real stall).
+#
+# usage_limit_patterns — BLOCKED, no auto-continue: credit exhaustion, the pane
+# line `You're out of usage credit` + `s. Run /usage-credits to keep using
+# <model> or /model to switch models.`, captured on psmux/Windows 11 (bmad-loop
+# 0.11.1) in runs 20260907-084618-824f (dev-1 and review-1) and
+# 20260907-090132-98e3 (dev-1 and dev-2). The model name is deliberately left
+# out of the anchor: it is whatever model the operator runs, so pinning it would
+# miss the next capture.
+#
+# usage_wait_patterns — blocked but WAITING for a reset Claude Code then
+# continues from on its own (autoContinueAtUsageLimit): the session-window
+# limit, the pane line `You've hit your session limi` + `t · resets <time>`,
+# optionally followed by a ` (<Area/City>)` zone. Captured twice: the 2026-09-07
+# psmux/Windows capture (zone suffix present) and run 20260913-165153-b850 on
+# macOS/tmux (no zone). The anchor stops at the `· resets` separator, which both
+# captures share. The same pane prints an advisory family thirteen times for
+# every two real hits — `You've used <N>% of your session` + ` limit · resets`
+# — from a session that is still working; `hit your` versus `used <N>% of your`
+# is what separates them, so the advisory can never reach this anchor.
+#
+# Both seeds keep ASCII apostrophes (both reports pasted ANSI-stripped logs), and
+# the single-character classes (`credit[s]`, `[.]`, `limi[t]`) keep each pattern
+# from matching its own line here — pinned, with the corpus, in
+# tests/test_env_fault_patterns.py. `[.]` rather than a backslash escape: a TOML
+# basic string rejects that escape.
+usage_limit_patterns = ["You're out of usage credit[s][.] Run /usage-credits"]
+usage_wait_patterns = ["You've hit your session limi[t] · resets"]
+
 # Force Claude Code's classic (inline/scrollback) renderer. The fullscreen TUI
 # (research preview, alt-screen ?1049h like vim/htop) repaints in place, so the
 # tmux pane capture only ever holds the final frame and the Log tab shows a single
diff --git a/src/bmad_loop/engine.py b/src/bmad_loop/engine.py
index 77e90bc6e..967a2767e 100644
--- a/src/bmad_loop/engine.py
+++ b/src/bmad_loop/engine.py
@@ -3078,6 +3078,8 @@ def _run_workflows(self, stage: str, task: StoryTask, seq: int) -> bool:
                 wf_extras["parked"] = True
                 if result.parked_evidence:
                     wf_extras["parked_evidence"] = result.parked_evidence
+            if result.usage_limited:
+                wf_extras["usage_limited"] = result.usage_limited
             self.journal.append(
                 "workflow-end",
                 plugin=lp.name,
@@ -8384,6 +8386,11 @@ def _session_end_extras(self, result: SessionResult, usage: TokenUsage | None =
             extras["parked"] = True
             if result.parked_evidence:
                 extras["parked_evidence"] = result.parked_evidence
+        # usage-limit diagnosis (#610): same present-only convention — the
+        # visible-pane line the adapter saw live, which exempted the env-fault
+        # verdict from the token veto.
+        if result.usage_limited:
+            extras["usage_limited"] = result.usage_limited
         # empty read-back diagnosis (#780): same present-only convention. The
         # last resultless-stop verdict lands here because nothing reads the
         # crumb file, so a spec nested out of the read-back's reach timed out
diff --git a/src/bmad_loop/escalation.py b/src/bmad_loop/escalation.py
index 72196fde7..906c8f752 100644
--- a/src/bmad_loop/escalation.py
+++ b/src/bmad_loop/escalation.py
@@ -215,7 +215,12 @@ def env_fault_pause_reason(role: str, result: SessionResult) -> str:
     tail also matches a transport pattern would otherwise pause blaming only the
     provider. Both facts hold and the operator needs both — a lost session is not
     evidence about the API, and a log pattern is not evidence the session
-    survived."""
+    survived.
+
+    A session the adapter saw live behind a usage limit (``result.usage_limited``,
+    #610) gets the usage-limit reason instead, so every pause site inherits it."""
+    if result.usage_limited:
+        return usage_limit_pause_reason(role, result)
     return f"environment fault: {session_failure_reason(role, result)} ({env_fault_detail(result)})"
 
 
@@ -227,7 +232,11 @@ def parked_pause_reason(role: str, result: SessionResult) -> str:
     lost-session suffix survives. The evidence names what the adapter saw — a
     hook signal (``Notification(permission_prompt) -> PermissionPrompt``) or a
     ``parked_prompt_patterns`` match on the visible pane — and the tail says why
-    the session ended `stalled` without the usual wake nudge."""
+    the session ended `stalled` without the usual wake nudge. A session parked
+    behind a usage limit (``result.usage_limited``, #610) gets the usage-limit
+    reason instead."""
+    if result.usage_limited:
+        return usage_limit_pause_reason(role, result)
     evidence = result.parked_evidence or "parked-session signal"
     return (
         f"parked: {session_failure_reason(role, result)} ({evidence}; the CLI was "
@@ -236,6 +245,22 @@ def parked_pause_reason(role: str, result: SessionResult) -> str:
     )
 
 
+def usage_limit_pause_reason(role: str, result: SessionResult) -> str:
+    """The pause reason for a session seen LIVE behind a usage limit (#610):
+    ``usage limit: <role> session <status> (<evidence>; ...)``.
+
+    Reached through ``env_fault_pause_reason`` and ``parked_pause_reason`` when
+    ``result.usage_limited`` is set, so no pause site names it directly. Composed
+    over `session_failure_reason`, like its siblings, so the #489 lost-session
+    suffix survives. The evidence is the visible-pane match; the tail names the
+    operator's ways out, since no retry gets past the limit on its own."""
+    return (
+        f"usage limit: {session_failure_reason(role, result)} ({result.usage_limited}; "
+        "the coding CLI is blocked by a usage limit — add credits, switch model or "
+        "wait for the reset, then bmad-loop resolve <run>)"
+    )
+
+
 def no_work_pause_reason(role: str, result: SessionResult) -> str:
     """The pause reason for a non-completed session that never did anything (#727):
     ``no work produced: <role> session <status> (...)``.
diff --git a/tests/test_engine.py b/tests/test_engine.py
index 7f8baafe2..0e5f0ba3e 100644
--- a/tests/test_engine.py
+++ b/tests/test_engine.py
@@ -15331,6 +15331,55 @@ def test_overruled_env_fault_is_journaled_and_retried(project):
     assert "env_fault_overruled" not in plain_end
 
 
+def test_usage_limited_session_end_is_journaled_and_paused(project):
+    """#610: a dev session the adapter saw live behind a usage limit (stalled +
+    parked, stamped env_fault with the pane evidence and exempt from the token
+    veto) pauses the run at the first story with the usage-limit reason, no
+    retry session burned, and `usage_limited` rides `session-end` (present-only).
+    ABLATION: drop the `usage_limited` extras line from `_session_end_extras`
+    and the session-end assertion fails."""
+    write_sprint(project, {"1-1-a": "ready-for-dev"})
+    # The captured credits line, split so this tracked file carries no line the
+    # shipped usage patterns match (test_pane_capture_patterns_do_not_match_this_repo).
+    evidence = (
+        "pane matched 'usage-pattern': You're out of usage credit"
+        + "s. Run /usage-credits to keep using Fable 5.1 or /model to switch models."
+    )
+    engine, adapter = make_engine(
+        project,
+        [
+            SessionResult(
+                status="stalled",
+                parked=True,
+                parked_evidence=evidence,
+                usage_limited=evidence,
+                env_fault=True,
+                env_fault_evidence=evidence,
+            )
+        ],
+    )
+    summary = engine.run()
+
+    assert summary.paused
+    assert [s.role for s in adapter.sessions] == ["dev"]  # no retry session burned
+    assert engine.state.tasks["1-1-a"].attempt == 1
+    assert engine.state.paused_stage == PAUSE_ESCALATION
+    assert engine.state.paused_reason is not None
+    assert "usage limit: dev session stalled" in engine.state.paused_reason
+    assert evidence in engine.state.paused_reason
+    dec = [e for e in engine.journal.entries() if e["kind"] == "dev-decision"][-1]
+    assert dec["action"] == "pause"
+    assert dec["reason"].startswith("usage limit: dev session stalled")
+    end = [e for e in engine.journal.entries() if e["kind"] == "session-end"][-1]
+    assert end["usage_limited"] == evidence
+    # guard pin: a plain stall's session-end omits the key. The journal is
+    # per-project, so only the second run's own last entry may be inspected.
+    engine2, _ = make_engine(project, [SessionResult(status="stalled")])
+    engine2.run()
+    plain_end = [e for e in engine2.journal.entries() if e["kind"] == "session-end"][-1]
+    assert "usage_limited" not in plain_end
+
+
 def test_session_env_fault_pauses_dev_without_burning_budget(project):
     """A dev session classified an environment fault (#194) pauses the run at the
     first story rather than charging the attempt; the decision + session-end carry
diff --git a/tests/test_env_fault.py b/tests/test_env_fault.py
index 28e44fbc0..d4708d28e 100644
--- a/tests/test_env_fault.py
+++ b/tests/test_env_fault.py
@@ -31,6 +31,8 @@ def __init__(self, logs_dir: Path):
         self.logs_dir = logs_dir
         self.crumbs: list[dict] = []
         self._env_fault_patterns = (regex.compile(r"^OUTAGE \w+"),)
+        self._usage_limit_patterns = ()
+        self._usage_wait_patterns = ()
 
     def _note_lifecycle(self, task_id: str, event: str, **fields: object) -> None:
         self.crumbs.append({"task": task_id, "event": event, **fields})
diff --git a/tests/test_env_fault_patterns.py b/tests/test_env_fault_patterns.py
index f703b8dad..0b36e1d55 100644
--- a/tests/test_env_fault_patterns.py
+++ b/tests/test_env_fault_patterns.py
@@ -1,4 +1,12 @@
-"""The shipped profiles' env_fault_patterns, held to both halves of the contract.
+"""The shipped profiles' pane patterns, held to both halves of the contract.
+
+"Pane patterns" are the three fields matched against what a session's log or
+visible pane says: env_fault_patterns (a provider outage) and the #610 pair
+usage_limit_patterns / usage_wait_patterns (a subscription limit the CLI is
+blocked behind, or waiting out). The usage pair is matched against the live pane
+AND, as ordinary env-fault families, against the post-mortem log tail, so it
+answers to exactly the same corpus as env_fault_patterns. parked_prompt_patterns
+is not held here (tests/test_profile.py pins it).
 
 A pattern that misses a real provider outage burns a story's retry budget on an
 environment fault (the bug that motivated this file). A pattern that fires on
@@ -9,7 +17,9 @@
 loosening a pattern.
 
 Only two profiles seed patterns, and only because captured output exists for
-them. The other four stay inert deliberately — see test_unseeded_profiles_stay_inert.
+them: opencode seeds env_fault_patterns, claude seeds all three fields
+(SEEDED_PANE_FIELDS). The other four stay inert deliberately — see
+test_unseeded_profiles_stay_inert.
 
 WHAT BAIT IS FOR. The tmux adapters match against a tmux pane capture, which
 contains the MODEL'S OWN OUTPUT: a story about quota handling prints this
@@ -68,6 +78,20 @@
 # Seeding nothing costs only the status quo. See test_unseeded_profiles_stay_inert.
 UNSEEDED_PROFILES = ("codex", "gemini", "copilot", "antigravity")
 ALL_PROFILES = SEEDED_PROFILES + UNSEEDED_PROFILES
+# The pane pattern fields this module holds to the corpus. Every BAIT-style
+# assertion below is made against the UNION of them: a usage-limit hit on a
+# healthy session parks the run exactly as an env-fault hit pauses it.
+PANE_PATTERN_FIELDS = ("env_fault_patterns", "usage_limit_patterns", "usage_wait_patterns")
+# Exactly the (profile, field) pairs that ship patterns, each backed by captured
+# output in REAL_BY_PROFILE. Listed rather than discovered, so withdrawing a seed
+# reddens test_pane_fields_are_seeded_exactly_where_listed instead of silently
+# shrinking every parametrization keyed on this.
+SEEDED_PANE_FIELDS = (
+    ("opencode", "env_fault_patterns"),
+    ("claude", "env_fault_patterns"),
+    ("claude", "usage_limit_patterns"),
+    ("claude", "usage_wait_patterns"),
+)
 
 # The two logfmt shapes `opencode serve` emitted during a real 5-hour provider
 # quota outage on the opencode-http adapter (zai-coding-plan/glm-5.2). The line
@@ -206,12 +230,13 @@
 # `claude` adapter. The last three come from Claude Code's own JSONL transcripts,
 # from entries structurally tagged `"isApiErrorMessage": true`.
 #
-# The quota class is still ABSENT, and deliberately so: no captured Claude Code
-# usage-limit line exists — not in this repo, not in #194/#323/#507, not in the
-# local transcripts. Seeding one needs a captured line with its run cited, the
-# bar test_unseeded_profiles_stay_inert states; a plausible-looking string is
-# exactly what that bar refuses. So an Anthropic plan's usage limit is still
-# unclassified on this adapter — a real, deliberately-left gap (#323).
+# The quota class is still ABSENT from env_fault_patterns, and deliberately so:
+# no captured Claude Code provider-side quota line exists — not in this repo, not
+# in #194/#323/#507, not in the local transcripts. Seeding one needs a captured
+# line with its run cited, the bar test_unseeded_profiles_stay_inert states; a
+# plausible-looking string is exactly what that bar refuses. The SUBSCRIPTION
+# usage limits Claude Code prints on its own screen were captured (#610) and live
+# in their own fields — see CLAUDE_USAGE_REAL.
 CLAUDE_REAL = [
     "API Error: Unable to connect to API (ConnectionRefused)",
     "API Error: Unable to connect to API: Self-signed certificate detected. "
@@ -223,10 +248,51 @@
     "try again in a moment. If it persists, check https://status.claude.com.",
 ]
 
-# Every profile with patterns, paired with the lines its own CLI actually emits.
+# Claude Code's subscription usage-limit lines (#610), as its pane prints them —
+# behind the `⎿` gutter glyph, with one or two spaces after it depending on the
+# terminal. Keyed by the field each must be caught by, because the two are
+# disjoint by contract: usage_limit_patterns is BLOCKED (credit exhaustion, an
+# operator must act), usage_wait_patterns is WAITING for a reset the CLI then
+# continues from by itself.
+#
+# Provenance, verbatim from #610:
+# * credits: psmux/Windows 11, bmad-loop 0.11.1, runs 20260907-084618-824f
+#   (dev-1 and review-1) and 20260907-090132-98e3 (dev-1 and dev-2) —
+#   `⎿ You're out of usage credits. Run /usage-credits to keep using Fable 5.1 or
+#   /model to switch models.`
+# * session limit: the 2026-09-07 psmux capture
+#   `⎿ You've hit your session limit · resets 12:50pm (Asia/Ho_Chi_Minh)`, and
+#   macOS/tmux run 20260913-165153-b850 `⎿  You've hit your session limit ·
+#   resets 7:20pm` (two spaces after the glyph, no zone).
+# The gutter-prefix and zone variants are the same captured sentences under the
+# other observed spacing, and with the optional zone on or off.
+_CLAUDE_CREDITS_SENTENCES = (
+    "You're out of usage credits. Run /usage-credits to keep using Fable 5.1 or "
+    "/model to switch models.",
+)
+_CLAUDE_SESSION_LIMIT_SENTENCES = (
+    "You've hit your session limit · resets 12:50pm (Asia/Ho_Chi_Minh)",
+    "You've hit your session limit · resets 12:50pm",
+    "You've hit your session limit · resets 7:20pm",
+    "You've hit your session limit · resets 7:20pm (Asia/Ho_Chi_Minh)",
+)
+_CLAUDE_PANE_GUTTERS = ("⎿ ", "⎿  ", "")
+CLAUDE_USAGE_REAL = {
+    field: [gutter + sentence for sentence in sentences for gutter in _CLAUDE_PANE_GUTTERS]
+    for field, sentences in (
+        ("usage_limit_patterns", _CLAUDE_CREDITS_SENTENCES),
+        ("usage_wait_patterns", _CLAUDE_SESSION_LIMIT_SENTENCES),
+    )
+}
+
+# Every seeded (profile, field), paired with the lines its own CLI actually emits.
 REAL_BY_PROFILE = [
-    (name, line)
-    for name, corpus in (("opencode", OPENCODE_REAL), ("claude", CLAUDE_REAL))
+    (name, field, line)
+    for name, field, corpus in (
+        ("opencode", "env_fault_patterns", OPENCODE_REAL),
+        ("claude", "env_fault_patterns", CLAUDE_REAL),
+        *(("claude", field, lines) for field, lines in CLAUDE_USAGE_REAL.items()),
+    )
     for line in corpus
 ]
 
@@ -238,9 +304,10 @@
 # only remaining anchor, so the test guarded nothing while looking thorough.
 #
 # So the bar for a line here is mechanical, and test_anchor_reaching_bait_is_not_
-# vacuous enforces it: every seeded profile must have at least one line carrying
-# its literal anchor. Lines below reproduce `error.error="AI_APICallError: ` (the
-# opencode anchor) inside ordinary healthy-session output.
+# vacuous enforces it: every seeded (profile, field) must have at least one line
+# carrying each of its literal anchors. Lines below reproduce
+# `error.error="AI_APICallError: ` (the opencode anchor) inside ordinary
+# healthy-session output.
 ANCHOR_REACHING_BAIT = [
     # The cause OUTSIDE the quoted error value: a real but UNRELATED provider
     # error whose trailing logfmt fields merely happen to contain a cause word.
@@ -316,6 +383,21 @@
     '  assert log == "API Error: 502 Overloaded"',
     "- [ ] AC-6: retry on API Error: 500 Overloaded and surface a banner",
     'it("renders API Error: 529 Internal server error", () => {',
+    # claude's usage-limit sentences (#610), each anchor carried but the sentence
+    # left unfinished — the opening words a story about a credits banner or a
+    # session-limit toast writes all day. The patterns run to `credits. Run
+    # /usage-credits` and `limit · resets`, so none of these reach a match. (The
+    # `You've used <N>% of your session limit` advisory never reaches the wait
+    # anchor at all — it is in BAIT.)
+    "You're out of usage credits!",
+    "You're out of usage credits.",
+    '  assert banner.text == "You\'re out of usage credits. Upgrade to keep going."',
+    "- [ ] AC-3: when You're out of usage credits, link to /usage-credits in the toast",
+    "docs: You're out of usage credits. Run the billing page to top up",
+    "You've hit your session limit, so the banner says to wait for the reset.",
+    "You've hit your session limit — resets at 7:20pm (em dash, not the CLI's separator)",
+    'expect(toast).toBe("You\'ve hit your session limit")',
+    "- [ ] AC-4: You've hit your session limit · show the reset time in the header",
 ]
 
 # The limit of content-based matching, pinned rather than papered over.
@@ -390,14 +472,30 @@ def _leading_literal(pattern: str) -> list[tuple[str, str]]:
     return tokens
 
 
+def _anchor_literal(pattern: str) -> str:
+    """One pattern's contribution to its anchor family: its leading literal run —
+    cut before the first single-character class when that run is the WHOLE
+    pattern. A wholly literal pattern (the #610 usage sentences) has nothing past
+    its leading literal, so an anchor spanning all of it could only be reached by
+    a line that matches; the first class is where the profile's own source line
+    stops spelling the sentence, and so where the rest of the pattern begins to
+    discriminate."""
+    tokens = _leading_literal(pattern)
+    if "".join(raw for raw, _ in tokens) == pattern:
+        cut = next((i for i, (raw, _) in enumerate(tokens) if raw.startswith("[")), len(tokens))
+        tokens = tokens[:cut]
+    return "".join(lit for _, lit in tokens)
+
+
 def _derive_anchors(patterns: tuple[str, ...]) -> tuple[str, ...]:
-    """Each anchor family's literal: the patterns' leading literal runs, grouped
-    by a shared prefix of at least MIN_ANCHOR_LEN characters, each group reduced
-    to its longest common prefix. One profile can key on more than one framing
-    (opencode: the 1.x server log's `error.error=` field and the 2.x
-    provider-errors line), and every family has to be reached by the corpus."""
+    """Each anchor family's literal: the patterns' anchor literals (see
+    `_anchor_literal`), grouped by a shared prefix of at least MIN_ANCHOR_LEN
+    characters, each group reduced to its longest common prefix. One field can
+    key on more than one framing (opencode: the 1.x server log's `error.error=`
+    field and the 2.x provider-errors line), and every family has to be reached
+    by the corpus."""
     anchors: list[str] = []
-    for literal in ("".join(lit for _, lit in _leading_literal(p)) for p in patterns):
+    for literal in (_anchor_literal(p) for p in patterns):
         for i, anchor in enumerate(anchors):
             n = 0
             while n < min(len(anchor), len(literal)) and anchor[n] == literal[n]:
@@ -422,7 +520,8 @@ def _leading_spelling(pattern: str, anchor: str) -> str | None:
 
 
 PROFILE_ANCHOR_LITERALS = {
-    name: _derive_anchors(get_profile(name).env_fault_patterns) for name in SEEDED_PROFILES
+    (name, field): _derive_anchors(getattr(get_profile(name), field))
+    for name, field in SEEDED_PANE_FIELDS
 }
 
 # Ordinary output from a healthy session working on a story that involves rate
@@ -515,8 +614,7 @@ def _leading_spelling(pattern: str, anchor: str) -> str | None:
     '  File "src/retry.py", line 41, in _raise_exhausted: '
     'RuntimeError("exceeded retry limit, last status: 429 Too Many Requests")',
     'raise UpstreamError("exceeded retry limit, last status: 503 Service Unavailable")',
-    "> exceeded retry limit, last status: 429 Too Many Requests   "
-    "(expected output, docs/retry.md)",
+    "> exceeded retry limit, last status: 429 Too Many Requests   (expected output, docs/retry.md)",
     '+    RESOURCE_EXHAUSTED_COPY = "Resource has been exhausted (e.g. check quota)."',
     '-        code: "rate_limit_exceeded",',
     'FIXTURE = {"error": {"code": 429, "message": "Resource has been exhausted '
@@ -528,11 +626,9 @@ def _leading_spelling(pattern: str, anchor: str) -> str | None:
     'it("gives up once it has exceeded retry limit, last status: 503", async () => {',
     "  1) rate limiter › Model call failed: rate_limited (expected, retries once)",
     "stdout | src/quota.test.ts > Model call failed: quota_exceeded",
-    '✗ should render "Quota exceeded for metric: generativelanguage.googleapis.com/x" '
-    "in the toast",
+    '✗ should render "Quota exceeded for metric: generativelanguage.googleapis.com/x" in the toast',
     "  ✓ TerminalQuotaError is raised after the third 429 (18ms)",
-    "# You have exhausted your daily quota on this model.  <- exact upstream copy, "
-    "do not reword",
+    "# You have exhausted your daily quota on this model.  <- exact upstream copy, do not reword",
     "* You exceeded your current quota, please check your plan and billing details.",
     "> Resource has been exhausted (e.g. check quota).",
     "  GaxiosError: request to https://generativelanguage.googleapis.com/v1beta/models/x "
@@ -589,6 +685,21 @@ def _leading_spelling(pattern: str, anchor: str) -> str | None:
     "2026-07-27T09:15:44.001Z ERROR codex_api_shim::mock: replaying error=http 429 "
     "fixture for the retry test",
     "- Sorry, you've hit a rate limit that restricts the number of Copilot model requests",
+    # ---------------------------------------------------------------------
+    # claude's usage-limit vocabulary (#610). The first three are Claude Code's
+    # OWN advisory, captured from a HEALTHY session in run 20260913-165153-b850
+    # (thirteen of them for every two real limit lines): the session is still
+    # working, so a hit here parks a run mid-story. `used <N>% of your` versus
+    # `hit your` is all that separates it from the wait line.
+    "You've used 90% of your session limit · resets 7:20pm…",
+    "You've used 96% of your session limit · resets 7:20pm…",
+    "You've used 97% of your session limit · resets 7:20pm…",
+    # …and a story implementing a credits banner, in its own words.
+    "AC-3: show a banner when the user is out of usage credits",
+    "PASS tests/test_credits.py::test_out_of_usage_credits_banner",
+    "docs: implement the /usage-credits banner copy",
+    "session limit reached — resets 3pm",
+    "Run /usage-credits to keep using the model",
 ]
 
 # A duplicated bait line silently weakens the corpus (it reads as coverage it is
@@ -596,12 +707,17 @@ def _leading_spelling(pattern: str, anchor: str) -> str | None:
 assert len(BAIT) == len(set(BAIT)), "BAIT contains duplicate lines"
 
 
-def _patterns(name: str) -> tuple[regex.Pattern[str], ...]:
-    return tuple(regex.compile(p) for p in get_profile(name).env_fault_patterns)
+def _patterns(
+    name: str, fields: tuple[str, ...] = PANE_PATTERN_FIELDS
+) -> tuple[regex.Pattern[str], ...]:
+    """``name``'s compiled patterns across ``fields`` — by default every pane
+    field, since a hit in any of them stops a healthy session."""
+    profile = get_profile(name)
+    return tuple(regex.compile(p) for field in fields for p in getattr(profile, field))
 
 
-def _matches(name: str, line: str) -> bool:
-    return any(p.search(line) for p in _patterns(name))
+def _matches(name: str, line: str, fields: tuple[str, ...] = PANE_PATTERN_FIELDS) -> bool:
+    return any(p.search(line) for p in _patterns(name, fields))
 
 
 @pytest.mark.parametrize("name", SEEDED_PROFILES)
@@ -638,23 +754,23 @@ def test_verbatim_citation_of_the_real_error_is_inseparable(line: str) -> None:
     their fixture to whatever path the code resolves — only the end-to-end test
     caught it. If the scanned file is ever repointed again, re-derive this safety
     argument before trusting it: see EnvFaultMixin.ENV_FAULT_LOG_SUFFIX."""
-    assert _matches("opencode", line)
+    assert _matches("opencode", line, ("env_fault_patterns",))
 
 
-@pytest.mark.parametrize("name", SEEDED_PROFILES)
-def test_anchor_reaching_bait_is_not_vacuous(name: str) -> None:
+@pytest.mark.parametrize(("name", "field"), SEEDED_PANE_FIELDS)
+def test_anchor_reaching_bait_is_not_vacuous(name: str, field: str) -> None:
     """Guards the guard. The test above is worthless unless its corpus actually
     contains the anchor under test — and it silently stopped doing so once, when
     the profile the corpus had been written for was withdrawn. Assert reachability
-    mechanically instead of trusting it, for every anchor family the profile
-    keys on."""
-    for anchor in PROFILE_ANCHOR_LITERALS[name]:
+    mechanically instead of trusting it, for every anchor family each seeded
+    field keys on."""
+    for anchor in PROFILE_ANCHOR_LITERALS[name, field]:
         reaching = [line for line in ANCHOR_REACHING_BAIT if anchor in line]
-        assert reaching, f"no ANCHOR_REACHING_BAIT line contains {name}'s anchor {anchor!r}"
+        assert reaching, f"no ANCHOR_REACHING_BAIT line contains {name}'s {field} anchor {anchor!r}"
 
 
-@pytest.mark.parametrize("name", SEEDED_PROFILES)
-def test_anchor_literal_is_the_live_patterns_anchor(name: str) -> None:
+@pytest.mark.parametrize(("name", "field"), SEEDED_PANE_FIELDS)
+def test_anchor_literal_is_the_live_patterns_anchor(name: str, field: str) -> None:
     """DW-373: guards the derivation of `PROFILE_ANCHOR_LITERALS`. The vacuity guard
     above is only as good as its input — an empty or trivially short anchor is
     `in` every bait line, so a derivation that silently went vacuous would pass it
@@ -663,36 +779,69 @@ def test_anchor_literal_is_the_live_patterns_anchor(name: str) -> None:
     tokens, run through the regex engine, must match the anchor exactly — so a
     decoding slip in `_leading_literal` cannot fake the prefix.
 
+    And an anchor must not by itself SATISFY a pattern: if it did, every line
+    reaching it would be a match, and the bait that reaches it could only ever
+    redden the test above — the trap a wholly literal pattern sets
+    (`_anchor_literal`).
+
     ABLATION: make `_derive_anchors` return ("",) (or stop decoding `[.]`) and this
     reddens; move a live pattern's anchor off the corpus and the guard above does."""
-    patterns = get_profile(name).env_fault_patterns
-    assert patterns, f"{name} ships no env_fault_patterns"
-    anchors = PROFILE_ANCHOR_LITERALS[name]
+    patterns = getattr(get_profile(name), field)
+    assert patterns, f"{name} ships no {field}"
+    anchors = PROFILE_ANCHOR_LITERALS[name, field]
     for anchor in anchors:
         assert (
             len(anchor) >= MIN_ANCHOR_LEN
-        ), f"{name}: derived anchor {anchor!r} is shorter than {MIN_ANCHOR_LEN} chars"
+        ), f"{name}.{field}: derived anchor {anchor!r} is shorter than {MIN_ANCHOR_LEN} chars"
+        assert not any(
+            regex.search(pattern, anchor) for pattern in patterns
+        ), f"{name}.{field}: derived anchor {anchor!r} alone matches a live pattern"
     for pattern in patterns:
         spellings = [
             (anchor, spelling)
             for anchor in anchors
             if (spelling := _leading_spelling(pattern, anchor)) is not None
         ]
-        assert spellings, f"{name}: live pattern {pattern!r} opens with none of {anchors!r}"
+        assert spellings, f"{name}.{field}: live pattern {pattern!r} opens with none of {anchors!r}"
         for anchor, spelling in spellings:
-            assert pattern.startswith(spelling), (name, pattern)
+            assert pattern.startswith(spelling), (name, field, pattern)
             assert regex.fullmatch(spelling, anchor), (
-                f"{name}: live pattern {pattern!r} does not open with anchor {anchor!r} "
-                f"(its leading spelling {spelling!r})"
+                f"{name}.{field}: live pattern {pattern!r} does not open with anchor "
+                f"{anchor!r} (its leading spelling {spelling!r})"
             )
 
 
-@pytest.mark.parametrize(("name", "line"), REAL_BY_PROFILE)
-def test_each_seeded_profile_catches_its_own_cli_error_lines(name: str, line: str) -> None:
-    """The false-negative half, per CLI. Each seeded profile is anchored on a
-    framing token its CLI emits, so a miss here means a real provider outage would
-    burn the story's retry budget instead of pausing the run."""
-    assert _matches(name, line), f"{name}.toml misses a real error line: {line[:120]}"
+def test_pane_fields_are_seeded_exactly_where_listed() -> None:
+    """SEEDED_PANE_FIELDS is the whole truth: every listed (profile, field) ships
+    patterns and no other does. A withdrawn seed must surface here rather than
+    silently drop its cases out of every parametrization keyed on the list, and a
+    new seed must arrive WITH its captured lines in REAL_BY_PROFILE."""
+    seeded = {
+        (name, field)
+        for name in ALL_PROFILES
+        for field in PANE_PATTERN_FIELDS
+        if getattr(get_profile(name), field)
+    }
+    assert seeded == set(SEEDED_PANE_FIELDS)
+    assert {(name, field) for name, field, _ in REAL_BY_PROFILE} == set(SEEDED_PANE_FIELDS)
+
+
+@pytest.mark.parametrize(("name", "field", "line"), REAL_BY_PROFILE)
+def test_each_seeded_profile_catches_its_own_cli_error_lines(
+    name: str, field: str, line: str
+) -> None:
+    """The false-negative half, per CLI and per field. Each seeded field is
+    anchored on a sentence its CLI emits, so a miss here means a real provider
+    outage burns the story's retry budget instead of pausing the run — or, for
+    the usage fields, a usage-limited session idles into a stall nudge and a
+    timeout instead of parking.
+
+    And ONLY by its own field: the fields are disjoint by contract. A credits line
+    read as a session-window wait sits out a reset that never comes; a provider
+    outage read as a usage limit escapes the token veto."""
+    assert _matches(name, line, (field,)), f"{name}.{field} misses a real line: {line[:120]}"
+    others = tuple(f for f in PANE_PATTERN_FIELDS if f != field)
+    assert not _matches(name, line, others), f"{name}: {line[:120]!r} matches outside {field}"
 
 
 @pytest.mark.parametrize("name", SEEDED_PROFILES)
@@ -708,6 +857,9 @@ def test_patterns_require_an_anchor_not_a_bare_cause(name: str) -> None:
         "type=provider.quota ",
         "provider.rate-limit",
         "type=provider.transport status=- attempt=2",
+        "session limit",
+        "/usage-credits",
+        "resets 3pm",
     ):
         assert not _matches(name, bare), f"{name}.toml classifies the bare cause {bare!r}"
 
@@ -716,18 +868,22 @@ def test_patterns_require_an_anchor_not_a_bare_cause(name: str) -> None:
 def test_shipped_patterns_do_not_match_their_own_profile_line(name: str) -> None:
     """A profile must not classify ITSELF. The pane log carries the model's own
     output, so a session that prints, greps or diffs its profile would otherwise
-    read its own configuration as a provider outage — one of the four non-test
-    false positives #507 names, and the most absurd of them.
+    read its own configuration as a provider outage (or a usage limit) — one of
+    the four non-test false positives #507 names, and the most absurd of them.
+    Every pane field's patterns are held to every line of the file, comments
+    included: the usage comments quote their captured sentences, split.
 
     What prevents it is the single-character classes in the shipped patterns
-    (`t[o]`, `respons[e]`, `5[2]9`, `5[0]0`): they change nothing about what the
-    regex MATCHES, and everything about what the regex's own source line matches.
-    This test is why they must not be "cleaned up"."""
+    (`t[o]`, `respons[e]`, `5[2]9`, `5[0]0`, `credit[s]`, `[.]`, `limi[t]`): they
+    change nothing about what the regex MATCHES, and everything about what the
+    regex's own source line matches. This test is why they must not be
+    "cleaned up"."""
     packaged = resources.files("bmad_loop.data").joinpath("profiles").joinpath(f"{name}.toml")
     # Compiled ONCE rather than per line via _matches: that helper re-resolves the
     # profile and recompiles its patterns on every call, which is free for a
     # one-line corpus entry and minutes across a whole file.
     patterns = _patterns(name)
+    assert patterns, f"{name} compiled no pane patterns; this guard would be vacuous"
     hits = [
         f"{name}.toml:{n}: {line.strip()[:120]}"
         for n, line in enumerate(packaged.read_text(encoding="utf-8").splitlines(), 1)
@@ -739,8 +895,8 @@ def test_shipped_patterns_do_not_match_their_own_profile_line(name: str) -> None
 # Files that hold matching lines ON PURPOSE, and are therefore excluded from the
 # repo-wide guard below.
 #
-# * this module is the corpus: CLAUDE_REAL quotes the captured CLI sentences
-#   verbatim, because a pattern may only be seeded from a captured line and the
+# * this module is the corpus: CLAUDE_REAL and CLAUDE_USAGE_REAL quote the
+#   captured CLI sentences verbatim, because a pattern may only be seeded from a captured line and the
 #   false-negative half has to assert against the real thing.
 # * test_generic_tmux.py drives the REAL classifier end to end, so its fixture
 #   logs must be lines the shipped patterns actually match.
@@ -753,7 +909,8 @@ def test_shipped_patterns_do_not_match_their_own_profile_line(name: str) -> None
 
 def test_pane_capture_patterns_do_not_match_this_repo() -> None:
     """#507's own methodology, kept as a standing guard: compile the pane-capture
-    profiles' patterns and scan every tracked file line-by-line.
+    profiles' patterns — every pane field, the #610 usage pair included — and
+    scan every tracked file line-by-line.
 
     bmad-loop is developed by bmad-loop, so this repo's own text is pane-log
     input. Measured against the tree this guard landed on, the withdrawn
@@ -768,7 +925,9 @@ def test_pane_capture_patterns_do_not_match_this_repo() -> None:
 
     This is what fails if a future CHANGELOG entry, doc bullet or profile comment
     writes the framing token and a cause on the SAME line; write them separated
-    (`API Error` … `<cause>`) instead. Only DELIBERATE_CORPUS_FILES are exempt.
+    (`API Error` … `<cause>`) instead — or, for a usage sentence, split it
+    (`You've hit your session limi` + `t · resets`). Only
+    DELIBERATE_CORPUS_FILES are exempt.
 
     opencode is out of scope on purpose, not by oversight: the file its patterns
     are matched against is `<task_id>.server.out` (see
@@ -796,6 +955,14 @@ def test_pane_capture_patterns_do_not_match_this_repo() -> None:
     # one-line corpus entry and minutes across every tracked line in the repo.
     patterns = [p for name in PANE_CAPTURE_PROFILES for p in _patterns(name)]
     assert patterns, "no pane-capture patterns compiled; this guard would be vacuous"
+    # Every seeded pane field of every pane-capture profile is in the scan — a
+    # field dropped from PANE_PATTERN_FIELDS would otherwise leave its patterns
+    # free to match this repo unseen.
+    for name, field in SEEDED_PANE_FIELDS:
+        if name in PANE_CAPTURE_PROFILES:
+            assert all(
+                any(p.pattern == raw for p in patterns) for raw in getattr(get_profile(name), field)
+            ), f"{name}.{field} is not in the repo scan"
 
     hits: list[str] = []
     corpus_hits: dict[str, int] = dict.fromkeys(DELIBERATE_CORPUS_FILES, 0)
@@ -812,8 +979,8 @@ def test_pane_capture_patterns_do_not_match_this_repo() -> None:
                 continue
             hits.append(f"{rel}:{n}: {line.strip()[:120]}")
     assert not hits, (
-        "tracked lines classify as an environment fault on a pane-capture profile; "
-        "split the framing token from the cause:\n" + "\n".join(hits)
+        "tracked lines classify as an environment fault or a usage limit on a "
+        "pane-capture profile; split the framing token from the cause:\n" + "\n".join(hits)
     )
     # Non-vacuity for the exemptions themselves: each excluded file must still be
     # carrying the matching lines it was excluded FOR. A file that stops matching
@@ -834,9 +1001,12 @@ def test_unseeded_profiles_stay_inert(name: str) -> None:
     nothing costs only the status quo.
 
     Do not seed these from a plausible-looking string. Seed them from a captured
-    log line, with the run it came from cited, and add it to REAL_BY_PROFILE and
-    this module's BAIT in the same change."""
-    assert get_profile(name).env_fault_patterns == ()
+    log line, with the run it came from cited, and add it to REAL_BY_PROFILE,
+    SEEDED_PANE_FIELDS and this module's BAIT in the same change. The bar covers
+    every pane field: a usage pattern stops a healthy session just as surely."""
+    profile = get_profile(name)
+    for field in PANE_PATTERN_FIELDS:
+        assert getattr(profile, field) == (), f"{name} seeds {field}"
 
 
 def test_v2_corpus_lines_are_what_the_adapter_writes() -> None:
@@ -856,7 +1026,11 @@ def test_v2_provider_error_line_is_model_free_shape(line: str) -> None:
     provider- or model-sourced is what made it match; and the same line behind
     any leading text — quoted in the transcript, a doc, a fixture — does not."""
     head = line.split(' message="', 1)[0] + " "
-    v2 = [p for p in _patterns("opencode") if p.pattern.startswith("^provider-error")]
+    v2 = [
+        p
+        for p in _patterns("opencode", ("env_fault_patterns",))
+        if p.pattern.startswith("^provider-error")
+    ]
     assert len(v2) == 1, "the opencode profile should ship one 2.x provider-error pattern"
     assert v2[0].search(head)
     assert v2[0].search(line)
diff --git a/tests/test_escalation.py b/tests/test_escalation.py
index 38961f260..f0db06adb 100644
--- a/tests/test_escalation.py
+++ b/tests/test_escalation.py
@@ -343,6 +343,58 @@ def test_review_env_fault_outranks_parked():
     assert decision.reason.startswith("environment fault: review session stalled")
 
 
+# The #610 credit-exhaustion pane line, split so this file carries no line the
+# shipped claude usage patterns match (test_pane_capture_patterns_do_not_match_this_repo).
+_USAGE_EVIDENCE = (
+    "pane matched 'usage-pattern': You're out of usage credit"
+    + "s. Run /usage-credits to keep using Fable 5.1 or /model to switch models."
+)
+
+
+def _usage_limited_results(status):
+    """The two shapes a live usage-limit sighting reaches a decider in: the
+    adapter's stalled + parked exit, and that result after `_classify_env_fault`
+    stamped it (env_fault with the pane evidence)."""
+    parked = SessionResult(
+        status=status, parked=True, parked_evidence=_USAGE_EVIDENCE, usage_limited=_USAGE_EVIDENCE
+    )
+    return [parked, dataclasses.replace(parked, env_fault=True, env_fault_evidence=_USAGE_EVIDENCE)]
+
+
+@pytest.mark.parametrize("attempt", [1, 2])  # budget left, then spent
+@pytest.mark.parametrize("status", ["stalled", "timeout"])
+def test_dev_usage_limited_pauses_with_usage_reason(attempt, status):
+    """A dev session seen live behind a usage limit (#610) PAUSEs with the
+    usage-limit reason — through either the env-fault or the parked arm, with
+    or without budget left — naming the evidence and the operator's ways out.
+    ABLATION: drop the `usage_limited` delegation from `env_fault_pause_reason`
+    / `parked_pause_reason` and the reason reads `environment fault:` /
+    `parked:` instead."""
+    for result in _usage_limited_results(status):
+        decision = decide_dev(_task(attempt=attempt), result, None, POLICY)
+        assert decision.action == Action.PAUSE
+        assert decision.reason.startswith(f"usage limit: dev session {status} (")
+        assert _USAGE_EVIDENCE in decision.reason
+        assert "bmad-loop resolve" in decision.reason
+
+
+@pytest.mark.parametrize("status", ["stalled", "timeout"])
+def test_review_usage_limited_pauses_with_usage_reason(status):
+    """The review-side twin: no review cycle is charged for a usage limit."""
+    for result in _usage_limited_results(status):
+        decision = decide_review_session(_task(attempt=1), result, POLICY)
+        assert decision.action == Action.PAUSE
+        assert decision.reason.startswith(f"usage limit: review session {status} (")
+        assert _USAGE_EVIDENCE in decision.reason
+
+
+def test_usage_limit_reason_keeps_the_lost_session_suffix():
+    """Composed over `session_failure_reason` (#489), like its siblings."""
+    vanished = SessionResult(status="stalled", usage_limited="x", session_vanished=True)
+    reason = escalation.usage_limit_pause_reason("dev", vanished)
+    assert reason.startswith("usage limit: dev session stalled: the multiplexer no longer")
+
+
 def test_dev_plain_noncompleted_still_retries_with_budget():
     """Guard pin: a NON-env-fault timeout with budget left still RETRYs — the
     env-fault branch must not swallow ordinary transient failures."""
diff --git a/tests/test_generic_tmux.py b/tests/test_generic_tmux.py
index 6d53ea04e..9dd06fb32 100644
--- a/tests/test_generic_tmux.py
+++ b/tests/test_generic_tmux.py
@@ -5293,21 +5293,25 @@ def test_classify_env_fault_inert_without_patterns(tmp_path):
     _env_fault_patterns is a cached_property, so a swap afterwards would leave the
     old patterns compiled (documented on the property)."""
     adapter = make_adapter(tmp_path)
-    adapter.profile = dataclasses.replace(adapter.profile, env_fault_patterns=())
-    assert adapter._env_fault_patterns == ()
+    # The tail scan also covers both usage-limit lists (#610), which claude
+    # seeds, so all three are emptied for the scan to be inert.
+    adapter.profile = dataclasses.replace(
+        adapter.profile, env_fault_patterns=(), usage_limit_patterns=(), usage_wait_patterns=()
+    )
+    assert adapter._tail_scan_patterns == ()
     _write_task_log(adapter, b"API Error: Connection closed mid-response\n")
     # DW-373: an empty pattern set matches nothing anyway, so the verdict alone
     # cannot tell the guard from a full scan. Pin the guard itself: the log is
-    # never even located. ABLATION: drop `not self._env_fault_patterns` from the
-    # guard and `opened` records the task.
+    # never even located. ABLATION: drop `if not self._tail_scan_patterns` from
+    # `_classify_env_fault` and `opened` records the task.
     opened: list[str] = []
-    real_log_path = adapter._env_fault_log_path
+    real_log_paths = adapter._env_fault_log_paths
 
-    def recording_log_path(task_id: str):
+    def recording_log_paths(task_id: str):
         opened.append(task_id)
-        return real_log_path(task_id)
+        return real_log_paths(task_id)
 
-    adapter._env_fault_log_path = recording_log_path
+    adapter._env_fault_log_paths = recording_log_paths
     result = _classify(adapter, "timeout")
     assert result.env_fault is False
     assert _lifecycle_lines(adapter, _ENV_FAULT_TASK) == []
@@ -5489,6 +5493,81 @@ def test_classify_env_fault_no_usage_read_without_pattern_hit(tmp_path):
     assert _lifecycle_lines(adapter, _ENV_FAULT_TASK) == []
 
 
+# The #610 captured Claude Code usage-limit lines, verbatim (this file is a
+# DELIBERATE_CORPUS_FILES entry: its fixtures must be lines the shipped patterns
+# really match). Credit exhaustion BLOCKS (usage_limit_patterns); the
+# session-window limit WAITS for its reset (usage_wait_patterns).
+USAGE_CREDITS_LINE = (
+    "⎿ You're out of usage credits. Run /usage-credits to keep using Fable 5.1 "
+    "or /model to switch models."
+)
+USAGE_SESSION_LINE = "⎿  You've hit your session limit · resets 7:20pm"
+
+
+def _usage_evidence(adapter, line=USAGE_CREDITS_LINE) -> str:
+    """The `usage_limited` string the live pane gate writes for `line`."""
+    return f"pane matched {adapter.profile.usage_limit_patterns[0]!r}: {line.strip()}"
+
+
+@pytest.mark.parametrize("status", ["timeout", "stalled"])
+def test_usage_limited_env_fault_is_not_overruled_by_tokens(tmp_path, status):
+    """A LIVE usage-limit sighting (`usage_limited`, #610) is the one env-fault
+    verdict the #764 token veto does not touch: tracked nonzero usage leaves
+    env_fault True with the pane evidence, usage is never read, the log tail is
+    never scanned (its own usage line would be overruled), and the classified
+    crumb says `usage_limited=True`.
+    ABLATION: drop the `if result.usage_limited is not None:` short-cut and the
+    tail match is overruled (env_fault False)."""
+    adapter = make_adapter(tmp_path)
+    reads: list[SessionResult] = []
+    adapter.read_usage = lambda r: (reads.append(r), TokenUsage(input_tokens=5))[1]
+    _write_task_log(adapter, f"implementing...\n{USAGE_CREDITS_LINE}\n".encode())
+    evidence = _usage_evidence(adapter)
+    handle = SessionHandle(task_id=_ENV_FAULT_TASK, native_id="@1")
+    live = SessionResult(
+        status=status, parked=True, parked_evidence=evidence, usage_limited=evidence
+    )
+    spec = make_spec(adapter.run_dir, task_id=_ENV_FAULT_TASK)
+    result = adapter._classify_env_fault(handle, spec, live)
+    assert result.env_fault is True
+    assert result.env_fault_evidence == evidence
+    assert result.env_fault_overruled is None
+    assert reads == []
+    events = _lifecycle_lines(adapter, _ENV_FAULT_TASK)
+    assert [e["event"] for e in events] == ["env-fault-classified"]
+    assert events[0]["usage_limited"] is True
+    assert events[0]["evidence"] == evidence
+    assert events[0]["status"] == status
+
+
+def test_tail_only_usage_match_is_still_overruled(tmp_path):
+    """The usage lists also scan the log TAIL as ordinary families (#610), and
+    there the #764 veto applies: a limit line the pane no longer showed, from a
+    session that billed tokens, is overruled like any other match. The untracked
+    twin pins that the tail scan really reaches the usage lists (else both
+    halves would read False for a scan that never matched)."""
+    log = f"implementing...\n{USAGE_CREDITS_LINE}\nback to work\n".encode()
+    tracked = make_adapter(tmp_path)
+    tracked.read_usage = lambda r: TokenUsage(input_tokens=5)
+    _write_task_log(tracked, log)
+    result = _classify(tracked, "timeout")
+    assert result.usage_limited is None
+    assert result.env_fault is False
+    assert result.env_fault_overruled is not None
+    assert "Run /usage-credits" in result.env_fault_overruled
+    assert [e["event"] for e in _lifecycle_lines(tracked, _ENV_FAULT_TASK)] == [
+        "env-fault-overruled"
+    ]
+
+    untracked = make_adapter(tmp_path)
+    untracked.read_usage = lambda r: None
+    _write_task_log(untracked, log)
+    kept = _classify(untracked, "timeout")
+    assert kept.env_fault is True
+    assert "Run /usage-credits" in kept.env_fault_evidence
+    assert kept.usage_limited is None  # the tail never sets the live field
+
+
 def test_run_overruled_timeout_is_plain_timeout(tmp_path):
     """Through run(): an overruled timeout stays a plain timeout, and the
     zero-token classifier does not read usage a second time.
@@ -11644,8 +11723,11 @@ def test_parked_notification_withholds_the_stall_nudge(tmp_path, monkeypatch, su
     assert result.parked is True
     assert result.parked_evidence == f"Notification({subtype}) -> {kind}"
     assert _stall_nudges(mux) == []
-    # The hook latch decides alone: the screen is never read.
-    assert mux.captures == []
+    # The hook latch decides parked alone: the parked patterns are never
+    # consulted, and the one capture is the usage-limit look (#610), which a
+    # screen without a limit line leaves unset.
+    assert mux.captures == ["@1"]
+    assert result.usage_limited is None
     # ...and the engine's dev decider pauses it with budget left (DW-348 AC).
     from bmad_loop.escalation import Action, decide_dev
     from bmad_loop.model import StoryTask
@@ -11792,8 +11874,9 @@ def test_pane_matched_prompt_withholds_the_stall_nudge(tmp_path, monkeypatch, li
     at grace expiry is withheld and the evidence quotes pattern and line. The
     screen carries ANSI styling and CR line ends, as a real capture can.
 
-    Ablation: delete `parked_now = self._pane_parked_evidence(handle)` and this
-    fails on the STALL_NUDGE_TEXT the mux then records."""
+    Ablation: delete `parked_now = parked_hit[0]` (the parked-set arm of the
+    shared `_pane_evidence` look in the stall-expiry gate) and this fails on the
+    STALL_NUDGE_TEXT the mux then records."""
     screen = f"\x1b[1m  {line}\x1b[0m\r\n\r\n❯ 1. No, exit\r\n  2. Yes, I accept\r\n"
     adapter, mux = _parked_adapter(tmp_path, monkeypatch, [], screen=screen)
     result = adapter.wait_for_completion(_dev_handle(), _dev_spec(tmp_path))
@@ -12020,12 +12103,189 @@ def test_profile_without_parked_patterns_never_captures(tmp_path, monkeypatch):
     """Inert for a profile that declares no patterns: the screen is not read."""
     adapter, mux = _parked_adapter(tmp_path, monkeypatch, [], screen=BYPASS_FOOTER, nudges=1)
     adapter._parked_prompt_patterns = ()
+    adapter._usage_limit_patterns = ()
+    adapter._usage_wait_patterns = ()
     result = adapter.wait_for_completion(_dev_handle(), _dev_spec(tmp_path))
     assert (result.status, result.parked) == ("stalled", False)
     assert mux.captures == []
     assert _lifecycle_events(adapter, "parked-probe-failed") == []  # config, not a fault
 
 
+# ------------------------------------------ usage-limit pane gates (#610)
+#
+# Claude Code stopped behind a usage limit idles exactly like a parked prompt;
+# the stall-expiry gate's one capture is matched against the usage-limit lists
+# too, and the timeout-fired path takes one look of its own. A live match is
+# recorded as `usage_limited` (which `_classify_env_fault` and both pause reasons
+# read); a dead window never is.
+
+
+@pytest.mark.parametrize(
+    ("line", "field"),
+    [
+        (USAGE_CREDITS_LINE, "usage_limit_patterns"),
+        (USAGE_SESSION_LINE, "usage_wait_patterns"),
+    ],
+)
+@pytest.mark.parametrize("nudges", [0, 2])
+def test_stall_expiry_on_usage_limit_line_is_parked_and_usage_limited(
+    tmp_path, monkeypatch, line, field, nudges
+):
+    """No hook latch, a usage-limit line on the visible pane: the stall-grace
+    expiry ends the session `stalled` + `parked`, with `usage_limited` naming
+    the matched pattern and quoting the line — whether a nudge was due (2) or
+    none is configured (0). Either list counts; one capture serves both the
+    parked and the usage patterns.
+
+    Ablation: drop `self._usage_pane_patterns` from the stall gate's
+    `_pane_evidence` call (usage_now stays None) and this fails on an unparked
+    stall with `usage_limited` None."""
+    screen = f"\x1b[2m{line}\x1b[0m\r\n\r\n❯ \r\n"
+    adapter, mux = _parked_adapter(tmp_path, monkeypatch, [], screen=screen, nudges=nudges)
+    result = adapter.wait_for_completion(_dev_handle(), _dev_spec(tmp_path))
+    assert (result.status, result.parked) == ("stalled", True)
+    assert result.usage_limited is not None
+    pattern = getattr(adapter.profile, field)[0]
+    assert result.usage_limited == f"pane matched {pattern!r}: {line.strip()}"
+    assert result.parked_evidence == result.usage_limited  # no latch: the limit IS the park
+    assert mux.sent == []
+    assert mux.captures == ["@1"]
+
+
+@pytest.mark.parametrize(
+    "events",
+    [[], [_hook_event("Notification", "idle_prompt")]],
+    ids=["no-latch", "idle-latch"],
+)
+def test_usage_line_withholds_the_stall_nudge(tmp_path, monkeypatch, events):
+    """Nudges available and a usage-limit line on screen: the wake nudge is
+    WITHHELD (it could only reproduce the limit line) and the
+    `stall-nudge-withheld` crumb carries `usage_limited`. With claude's
+    `idle_prompt` latch already supplying the parked evidence, the usage look
+    still runs and is still recorded.
+
+    Ablation: drop `self._usage_pane_patterns` from the stall gate's
+    `_pane_evidence` call and the no-latch case sends two STALL_NUDGE_TEXTs; the
+    latched case loses `usage_limited` from the crumb and the result."""
+    adapter, mux = _parked_adapter(
+        tmp_path, monkeypatch, events, screen=f"{USAGE_CREDITS_LINE}\n", nudges=2
+    )
+    result = adapter.wait_for_completion(_dev_handle(), _dev_spec(tmp_path))
+    evidence = _usage_evidence(adapter)
+    assert _stall_nudges(mux) == []
+    assert (result.status, result.parked) == ("stalled", True)
+    assert result.usage_limited == evidence
+    (withheld,) = _lifecycle_events(adapter, "stall-nudge-withheld")
+    assert withheld["usage_limited"] == evidence
+    assert withheld["nudge_due"] is True
+    if events:
+        assert result.parked_evidence == "Notification(idle_prompt) -> IdlePrompt"
+        assert withheld["evidence"] == "Notification(idle_prompt) -> IdlePrompt"
+    else:
+        assert withheld["evidence"] == evidence
+
+
+def test_timeout_with_usage_line_visible_is_usage_limited(tmp_path, monkeypatch):
+    """The session clock ran out while the CLI sat behind the session-window
+    limit: the timeout-fired path's one look at the pane records `usage_limited`
+    (the status stays `timeout`). A clean screen on the same path leaves it
+    unset, so the field is the match's, not the timeout's."""
+    adapter, clock = _timeout_clock_adapter(tmp_path, monkeypatch)
+    mux = _UnitMux(screen=f"working…\n{USAGE_SESSION_LINE}\n")
+    adapter.mux = mux
+
+    def advance(call_n):
+        clock["mono"] += 11.0
+
+    adapter.watcher = _ScriptedWatcher([], on_call=advance)
+    result = adapter.wait_for_completion(_dev_handle(), _short_spec(tmp_path))
+    assert result.status == "timeout"
+    pattern = adapter.profile.usage_wait_patterns[0]
+    assert result.usage_limited == f"pane matched {pattern!r}: {USAGE_SESSION_LINE.strip()}"
+    assert mux.captures == ["@1"]
+
+    mux.screen = "working…\n❯ \n"
+    clock["mono"] = 1000.0
+    adapter.watcher = _ScriptedWatcher([], on_call=advance)
+    clean = adapter.wait_for_completion(_dev_handle(), _short_spec(tmp_path))
+    assert clean.status == "timeout"
+    assert clean.usage_limited is None
+
+
+def test_dead_window_is_never_usage_limited(tmp_path, monkeypatch):
+    """A usage-limit line still captures off a dead (remain-on-exit) pane, but a
+    CLI that is gone is not waiting on a limit: the stall re-probe finding the
+    window dead is `crashed`, never parked or usage-limited, and a timeout whose
+    liveness check finds it dead leaves `usage_limited` unset."""
+    stall_dir = tmp_path / "stall"
+    stall_dir.mkdir()
+    adapter, mux = _parked_adapter(
+        stall_dir, monkeypatch, [], screen=f"{USAGE_CREDITS_LINE}\n", nudges=2
+    )
+    # alive on every tick, dead at the re-probe right after the gate's verdict
+    adapter._window_alive = lambda handle: not _lifecycle_events(adapter, "stall-nudge-withheld")
+    result = adapter.wait_for_completion(_dev_handle(), _dev_spec(stall_dir))
+    assert result.status == "crashed"
+    assert result.parked is False
+    assert result.usage_limited is None
+    assert _stall_nudges(mux) == []
+    assert mux.captures == ["@1"]  # the line WAS seen: the probe is what declined it
+
+    timeout_dir = tmp_path / "timeout"
+    timeout_dir.mkdir()
+    timed, clock = _timeout_clock_adapter(timeout_dir, monkeypatch)
+    timed_mux = _UnitMux(screen=f"{USAGE_SESSION_LINE}\n")
+    timed.mux = timed_mux
+    timed._window_alive = lambda handle: not _lifecycle_events(timed, "timeout-fired")
+
+    def advance(call_n):
+        clock["mono"] += 11.0
+
+    timed.watcher = _ScriptedWatcher([], on_call=advance)
+    late = timed.wait_for_completion(_dev_handle(), _short_spec(timeout_dir))
+    assert late.status == "timeout"
+    assert late.usage_limited is None
+    assert timed_mux.captures == ["@1"]
+
+
+def test_profile_without_usage_patterns_never_captures_for_them(tmp_path, monkeypatch):
+    """Inert without usage patterns: with a hook latch deciding parked (so the
+    parked patterns are not consulted either) the stall gate never reads the
+    screen, and neither does the timeout-fired path — a limit line on screen
+    notwithstanding."""
+    stall_dir = tmp_path / "stall"
+    stall_dir.mkdir()
+    adapter, mux = _parked_adapter(
+        stall_dir,
+        monkeypatch,
+        [_hook_event("Notification", "permission_prompt")],
+        screen=f"{USAGE_CREDITS_LINE}\n",
+    )
+    adapter._usage_limit_patterns = ()
+    adapter._usage_wait_patterns = ()
+    result = adapter.wait_for_completion(_dev_handle(), _dev_spec(stall_dir))
+    assert (result.status, result.parked) == ("stalled", True)
+    assert result.usage_limited is None
+    assert mux.captures == []
+    assert _lifecycle_events(adapter, "parked-probe-failed") == []  # config, not a fault
+
+    timeout_dir = tmp_path / "timeout"
+    timeout_dir.mkdir()
+    timed, clock = _timeout_clock_adapter(timeout_dir, monkeypatch)
+    timed_mux = _UnitMux(screen=f"{USAGE_SESSION_LINE}\n")
+    timed.mux = timed_mux
+    timed._usage_limit_patterns = ()
+    timed._usage_wait_patterns = ()
+
+    def advance(call_n):
+        clock["mono"] += 11.0
+
+    timed.watcher = _ScriptedWatcher([], on_call=advance)
+    late = timed.wait_for_completion(_dev_handle(), _short_spec(timeout_dir))
+    assert (late.status, late.usage_limited) == ("timeout", None)
+    assert timed_mux.captures == []
+
+
 def test_capture_pane_argv_reads_the_visible_screen(monkeypatch, force_tmux_backend):
     """`capture-pane -p -t <window>`: the visible screen to stdout, no `-S`/`-E`
     scrollback range — the question is what is on screen NOW (DW-350)."""
diff --git a/tests/test_portability_guard.py b/tests/test_portability_guard.py
index c546f50d4..e8929d705 100644
--- a/tests/test_portability_guard.py
+++ b/tests/test_portability_guard.py
@@ -1008,6 +1008,10 @@
         "tokens_weighted",
         "total",
         "trigger",
+        # `session-end` / `workflow-end` (#610): the visible-pane line a usage-limit
+        # pattern matched live — the matched profile pattern plus the quoted pane
+        # line, the same class of excerpt as `parked_evidence`.
+        "usage_limited",
         "verification_sequence",
         "verification_stage",
         "via",
@@ -1185,6 +1189,7 @@
             "session_vanished",
             "parked",
             "parked_evidence",
+            "usage_limited",
         }
     ),
     # The plugin bus's `_log` forwards its OWN `**fields` parameter, so the keys
diff --git a/tests/test_profile.py b/tests/test_profile.py
index 98f0a5358..28a28c335 100644
--- a/tests/test_profile.py
+++ b/tests/test_profile.py
@@ -158,7 +158,10 @@ def test_env_fault_patterns_parse_from_overlay(tmp_path):
     assert prof.env_fault_patterns == ("API Error.*refused", "socket hang up")
 
 
-@pytest.mark.parametrize("field", ["env_fault_patterns", "parked_prompt_patterns"])
+@pytest.mark.parametrize(
+    "field",
+    ["env_fault_patterns", "parked_prompt_patterns", "usage_limit_patterns", "usage_wait_patterns"],
+)
 def test_deeply_nested_pattern_is_a_profile_error_not_a_bare_recursion_error(tmp_path, field):
     """DW-373: `regex.compile` answers a deeply nested pattern with RecursionError,
     not `regex.error` — it must still surface as a ProfileError naming the field,
@@ -267,6 +270,134 @@ def test_shipped_claude_parked_patterns_do_not_match_their_own_profile_line():
     assert hits == []
 
 
+_USAGE_FIELDS = ("usage_limit_patterns", "usage_wait_patterns")
+
+
+def test_usage_fields_default_empty_when_unset(tmp_path):
+    # MINIMAL_PROFILE declares neither -> both inert (#610)
+    profiles_dir = tmp_path / ".bmad-loop" / "profiles"
+    profiles_dir.mkdir(parents=True)
+    (profiles_dir / "mycli.toml").write_text(MINIMAL_PROFILE, encoding="utf-8", newline="")
+    prof = load_profiles(tmp_path)["mycli"]
+    assert prof.usage_limit_patterns == ()
+    assert prof.usage_wait_patterns == ()
+
+
+def test_usage_fields_parse_from_overlay(tmp_path):
+    # a project overlay may seed either list; each parses into a tuple verbatim and
+    # independently of the other (compilation validated, see the invalid-regex cases)
+    profiles_dir = tmp_path / ".bmad-loop" / "profiles"
+    profiles_dir.mkdir(parents=True)
+    (profiles_dir / "mycli.toml").write_text(
+        MINIMAL_PROFILE.replace(
+            "[hooks]",
+            'usage_limit_patterns = ["Out of credit[s]", "Quota gon[e]"]\n'
+            'usage_wait_patterns = ["Limit hi[t] · resets"]\n[hooks]',
+        ),
+        encoding="utf-8",
+        newline="",
+    )
+    prof = load_profiles(tmp_path)["mycli"]
+    assert prof.usage_limit_patterns == ("Out of credit[s]", "Quota gon[e]")
+    assert prof.usage_wait_patterns == ("Limit hi[t] · resets",)
+    # neither list leaks into the env-fault or parked-prompt fields
+    assert prof.env_fault_patterns == ()
+    assert prof.parked_prompt_patterns == ()
+
+
+@pytest.mark.parametrize("field", _USAGE_FIELDS)
+def test_usage_field_invalid_regex_is_a_profile_error(tmp_path, field):
+    """An invalid usage pattern fails fast at parse, naming its own field — not at
+    match time inside a live pane check, where the caller degrades."""
+    profiles_dir = tmp_path / ".bmad-loop" / "profiles"
+    profiles_dir.mkdir(parents=True)
+    (profiles_dir / "mycli.toml").write_text(
+        MINIMAL_PROFILE.replace("[hooks]", f'{field} = ["resets(unbalanced"]\n[hooks]'),
+        encoding="utf-8",
+        newline="",
+    )
+    with pytest.raises(ProfileError, match=f"{field} entry is not a valid regex"):
+        load_profiles(tmp_path)
+
+
+@pytest.mark.parametrize("field", _USAGE_FIELDS)
+def test_usage_field_must_be_a_list_of_strings(tmp_path, field):
+    profiles_dir = tmp_path / ".bmad-loop" / "profiles"
+    profiles_dir.mkdir(parents=True)
+    (profiles_dir / "mycli.toml").write_text(
+        MINIMAL_PROFILE.replace("[hooks]", f'{field} = "resets"\n[hooks]'),
+        encoding="utf-8",
+        newline="",
+    )
+    with pytest.raises(ProfileError, match=f"{field} must be a list of strings"):
+        load_profiles(tmp_path)
+
+
+# The #610 captured pane lines, concatenated so this file holds no line the
+# shipped patterns match (only tests/test_env_fault_patterns.py and
+# tests/test_generic_tmux.py may). Credits: psmux/Windows 11, runs
+# 20260907-084618-824f and 20260907-090132-98e3. Session limit: the 2026-09-07
+# psmux capture (zone suffix) and macOS/tmux run 20260913-165153-b850 (two spaces
+# after the gutter glyph, no zone).
+_CAPTURED_USAGE_LIMIT_LINES = (
+    "⎿ You're out of usage credit"
+    + "s. Run /usage-credits to keep using Fable 5.1 or /model to switch models.",
+)
+_CAPTURED_USAGE_WAIT_LINES = (
+    "⎿ You've hit your session limi" + "t · resets 12:50pm (Asia/Ho_Chi_Minh)",
+    "⎿  You've hit your session limi" + "t · resets 7:20pm",
+)
+
+
+def test_shipped_claude_usage_patterns_match_the_captured_610_lines():
+    """Each seeded usage pattern matches the lines it was seeded from, in its OWN
+    list only: the two lists are disjoint by contract (blocked vs waiting), so a
+    credits line read as a session-window wait would sit out a reset that never
+    comes."""
+    import regex
+
+    claude = get_profile("claude")
+    limit = [regex.compile(p) for p in claude.usage_limit_patterns]
+    wait = [regex.compile(p) for p in claude.usage_wait_patterns]
+    assert limit and wait
+    for line in _CAPTURED_USAGE_LIMIT_LINES:
+        assert any(p.search(line) for p in limit), line
+        assert not any(p.search(line) for p in wait), line
+    for line in _CAPTURED_USAGE_WAIT_LINES:
+        assert any(p.search(line) for p in wait), line
+        assert not any(p.search(line) for p in limit), line
+    # the advisory a still-working session prints must never read as the wait
+    advisory = "You've used 90% of your session limi" + "t · resets 7:20pm"
+    assert not any(p.search(advisory) for p in limit + wait)
+
+
+def test_shipped_claude_usage_patterns_do_not_match_their_own_profile_line():
+    """A session that prints or diffs claude.toml must not read as usage-limited:
+    the single-character classes (`credit[s]`, `[.]`, `limi[t]`) exist for this. Do
+    not "clean" them up."""
+    import regex
+
+    claude = get_profile("claude")
+    patterns = [regex.compile(p) for f in _USAGE_FIELDS for p in getattr(claude, f)]
+    assert patterns
+    text = (
+        resources.files("bmad_loop.data")
+        .joinpath("profiles")
+        .joinpath("claude.toml")
+        .read_text(encoding="utf-8")
+    )
+    hits = [line for line in text.splitlines() if any(p.search(line) for p in patterns)]
+    assert hits == []
+
+
+def test_only_claude_seeds_usage_patterns():
+    # the other built-ins opt in on their own captured evidence; none has yet
+    for name, prof in load_profiles().items():
+        if name != "claude":
+            assert prof.usage_limit_patterns == (), name
+            assert prof.usage_wait_patterns == (), name
+
+
 def test_skill_tree_defaults_when_unset():
     # MINIMAL_PROFILE omits skill_tree -> defaults to .claude/skills
     assert get_profile("claude").skill_tree == ".claude/skills"
@@ -1112,7 +1243,7 @@ def _plugin_profile(name="acme", adapter="acme", **over):
 def test_entry_point_profile_is_discovered(profile_scan):
     """A pip-installed profile provider (a callable returning CLIProfiles) makes
     its profile resolvable with no project TOML — the zero-config selection path."""
-    profile_scan(_FakeEntryPoint("acme", lambda: (lambda: [_plugin_profile()])))
+    profile_scan(_FakeEntryPoint("acme", lambda: lambda: [_plugin_profile()]))
     prof = get_profile("acme")
     assert prof.name == "acme" and prof.adapter == "acme"
     assert profile_mod.external_profile_errors() == {}
@@ -1293,6 +1424,9 @@ def test_profile_scan_failure_degrades(profile_scan):
         ),
         ({"hooks": HookSpec("none", "", {}, {"x": "PermissionPrompt"})}, "hookless"),
         ({"parked_prompt_patterns": ("Enter(unbalanced",)}, "not a valid regex"),
+        # the #610 usage-limit pane patterns, each list on its own
+        ({"usage_limit_patterns": ("credits(unbalanced",)}, "usage_limit_patterns"),
+        ({"usage_wait_patterns": ("resets(unbalanced",)}, "usage_wait_patterns"),
         # the remaining value-level knobs
         ({"usage_parser": "magic"}, "usage_parser"),
         ({"usage_grace_s": -1.0}, "usage_grace_s"),

From 38fb19f7b022f57e8b502f9383d36b1f8750e3ec Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Sun, 25 Oct 2026 12:55:49 -0700
Subject: [PATCH 2/8] fix(adapters): hold the session timeout while Claude Code
 waits out a usage-limit reset (DW-396)

Claude Code behind a session-window limit waits for the reset and continues
by itself, repainting its pane, so the stall timer never fires while
session_timeout_min keeps counting: the session timed out after the CLI
resumed and the story was deferred.

New policy key limits.quota_wait_max_min (default 300, 0 = off), handed to
every engine-driven session as SessionSpec.quota_wait_max_s. The wait opens
at a heartbeat when the transcript has been idle for 90 s, no tool call is
open, the visible pane matches usage_wait_patterns and no permission/quota
prompt is latched. While it is open both session deadlines are re-based on
every tick (the one sanctioned exception to #157's never-extend rule), stall
expiries re-arm without a nudge and a result-less Stop withholds the stop
nudge. Transcript movement or a permission/quota latch ends it; an
idle_prompt latch or the line scrolling away does not. At the cap, measured
on both clocks, the session ends stalled + parked with the usage evidence
through the shared stall exit. The token-budget grace is not frozen.

quota-wait-started / -ended / -cap go to the lifecycle crumbs and the run
journal; heartbeat.json gains quota_waiting / quota_wait_s, and
SessionResult.quota_wait_s rides session-end and workflow-end when positive.
---
 CHANGELOG.md                          |   7 +
 docs/reference/configuration.md       |   1 +
 src/bmad_loop/adapters/base.py        |  14 +
 src/bmad_loop/adapters/generic.py     | 278 +++++++++++++++-
 src/bmad_loop/data/settings/core.toml |   6 +
 src/bmad_loop/engine.py               |   9 +
 src/bmad_loop/policy.py               |  15 +
 tests/test_engine.py                  |  21 ++
 tests/test_generic_tmux.py            | 450 ++++++++++++++++++++++++++
 tests/test_policy.py                  |  13 +
 tests/test_portability_guard.py       |  25 ++
 11 files changed, 838 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7b0294f20..de6d9c905 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,13 @@ breaking changes may land in a minor release.
 
 ### Added
 
+- Add `limits.quota_wait_max_min` (default 300; 0 = off): while the visible pane shows
+  Claude Code waiting out a usage-window reset and the transcript is idle, the session
+  timeout stands still and the stall nudge is held, so the session no longer burns
+  `session_timeout_min` behind the limit and can finish after the CLI's own
+  auto-continue. Past the cap the session pauses with a usage-limit reason.
+  `heartbeat.json` gains `quota_waiting` / `quota_wait_s`, `session-end` gains
+  `quota_wait_s`, and the journal gains `quota-wait-started` / `-ended` / `-cap`.
 - Add the experimental `tickets` work source for BMAD v7 initiative ticket trees
   (`[stories] source = "tickets"`): dispatch `bmad-build-auto ticket <ref>` in initiative
   build order, verify each plan at `built`, and mark it `done` through `tickets.py mark`
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index a3f33a1b2..6674e9af7 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -97,6 +97,7 @@ Cycle/attempt caps, timeout & token budget.
 | `dev_stall_nudges` | integer | `2` | ≥ 0 | best-effort wake nudges for a silent dev/review session on grace expiry before it is called stalled; transport activity re-arms the grace and fresh Stop/idle evidence restores this budget · 0 = stall on grace expiry |
 | `dev_stall_nudges_cap` | integer | `6` | ≥ 0 | total (never-restored) best-effort stall nudges for a dev/review session; bounds launch-time recovery and Stop/idle budget refills because an accepted nudge does not guarantee a wake · 0 = stall on first grace expiry |
 | `workflow_stall_nudges_cap` | integer | `3` | ≥ 0 | total (never-restored) stall nudges for an injected plugin-workflow session before it is called stalled; bounds a session that finished its work but never wrote its completion marker · 0 = stall on first grace expiry |
+| `quota_wait_max_min` | integer | `300` | ≥ 0 | cumulative minutes one session may sit in a usage-limit wait (the visible pane shows the coding CLI waiting out a usage-window reset it continues from by itself, and the transcript is idle) with its session timeout frozen and its stall nudge held · past the cap the session ends parked with usage-limit evidence · 0 = off (the timeout keeps counting through the wait) |
 | `dev_contract_nudge` | boolean | `true` |  | ON: one targeted nudge per session when a Stop finds a spec finalized to a terminal frontmatter status but missing its `## Auto Run Result` marker, asking the skill to append it and end its turn (sent exactly once, never refilled, touches no stall counters) · OFF: rely only on harness-side frontmatter synthesis |
 | `max_tokens_per_story` | integer | `2000000` | ≥ 1 | advisory cap on one story's cumulative weighted spend across all its sessions, re-checked at every session boundary · crossing it raises one ATTENTION + desktop notice per story and nothing else — the story runs on · for a cap that can END a session see session budget mode below |
 | `cache_read_weight` | float | `0.1` | 0.0–1.0 | weight of cache-read tokens in every token total — budgets and displays alike · cache reads bill at ~0.1x base input on all supported vendors and are 80-95% of the raw count on agentic work, so the default keeps totals proportional to spend rather than to context re-reads · 1.0 = count cache reads at full price (raw) |
diff --git a/src/bmad_loop/adapters/base.py b/src/bmad_loop/adapters/base.py
index ac4eba07d..1f0734874 100644
--- a/src/bmad_loop/adapters/base.py
+++ b/src/bmad_loop/adapters/base.py
@@ -237,6 +237,15 @@ class SessionSpec:
     # only, never a scan for other specs (#261). A relative entry is rebased on
     # `cwd`. Empty for every v6 session. Both kept LAST, after `effort`.
     fallback_result_dirs: tuple[Path, ...] = ()
+    # Usage-limit wait cap (DW-396), in seconds: the most cumulative time this
+    # session may sit in a quota wait — the visible pane matches the profile's
+    # `usage_wait_patterns` while the transcript is idle — with its session
+    # timeout frozen and its stall nudge held. Past it the session ends stalled +
+    # parked with usage-limit evidence. 0.0 (the raw constructor default) = off,
+    # so adapters constructed outside the engine (tests, MockAdapter, resolve)
+    # keep the plain timeout. The engine sets limits.quota_wait_max_min * 60 for
+    # every session it drives. Kept LAST so positional constructions stay valid.
+    quota_wait_max_s: float = 0.0
 
 
 @dataclass(frozen=True)
@@ -352,6 +361,11 @@ class SessionResult:
     # limit is on screen now, not a stale match), and both pause reasons name it
     # as a usage limit. APPENDED.
     usage_limited: str | None = None
+    # Cumulative seconds this session spent in a usage-limit quota wait (DW-396)
+    # with its session timeout frozen; 0.0 = it never waited. Carried on every
+    # result `wait_for_completion` returns, journaled on `session-end` only when
+    # positive. APPENDED.
+    quota_wait_s: float = 0.0
 
 
 class CodingCLIAdapter(ABC):
diff --git a/src/bmad_loop/adapters/generic.py b/src/bmad_loop/adapters/generic.py
index 1c991f8b5..21886af9a 100644
--- a/src/bmad_loop/adapters/generic.py
+++ b/src/bmad_loop/adapters/generic.py
@@ -194,9 +194,52 @@ class _IdleTracker:
     tool_scan_failures: int = 0
 
 
+@dataclass
+class _QuotaWait:
+    """Per-session state of the usage-limit quota wait (DW-396), owned by one
+    `wait_for_completion` call.
+
+    `waiting` is the open-wait flag. While it is set the wait loop re-bases both
+    session deadlines to `frozen_remaining` on every tick, so the timeout stands
+    still. `started_mono` / `started_wall` are the open wait's start on each
+    clock. An open wait's length is the LONGER of the two elapsed spans, so a
+    host suspend (monotonic frozen, wall running) cannot stretch the cap.
+    `closed_s` sums the waits that already ended; `evidence` is the pane line
+    that admitted the open one."""
+
+    waiting: bool = False
+    started_mono: float = 0.0
+    started_wall: float = 0.0
+    frozen_remaining: float = 0.0
+    closed_s: float = 0.0
+    evidence: str | None = None
+
+    def open_s(self) -> float:
+        if not self.waiting:
+            return 0.0
+        return max(time.monotonic() - self.started_mono, time.time() - self.started_wall, 0.0)
+
+    def total_s(self) -> float:
+        return self.closed_s + self.open_s()
+
+
 # min spacing between heartbeat.json overwrites in wait_for_completion; the
 # heartbeat's staleness is what makes a frozen orchestrator (#157) diagnosable.
 HEARTBEAT_INTERVAL_S = 30.0
+# Usage-limit quota wait (DW-396): how long the live transcript must have held
+# still (three heartbeats) before a visible `usage_wait_patterns` line may freeze
+# the session timeout. A CLI still writing its transcript is working, not
+# waiting out a reset.
+QUOTA_WAIT_IDLE_S = 90.0
+# The floor on the timeout a quota wait freezes, and so on what the session
+# resumes with once the CLI continues: a wait admitted with seconds to spare
+# must leave the auto-continued turn room to finish and Stop.
+QUOTA_WAIT_MIN_REMAINING_S = 120.0
+# The parked-latch kinds that block a quota wait (DW-396): a CLI asking a human
+# for permission or a quota decision is not going to continue by itself. An
+# `IdlePrompt` is deliberately absent — claude sends `idle_prompt` ~60 s after
+# every finished turn, including the one the usage limit ended.
+QUOTA_WAIT_BLOCKING_KINDS = frozenset({"QuotaPrompt", "PermissionPrompt"})
 # Startup-frame window for the #727 no-work verdict: pane-log growth detected on a
 # tick later than this many seconds after the wait loop started counts as work;
 # growth inside it is the CLI painting its first frame — a banner, a menu, a
@@ -1177,12 +1220,29 @@ def start_session(self, spec: SessionSpec) -> SessionHandle:
         )
 
     def wait_for_completion(self, handle: SessionHandle, spec: SessionSpec) -> SessionResult:
+        """`_wait_loop`, with the quota wait's total carried onto whatever it
+        returns (DW-396). A wait still open at the exit (a Stop with a result,
+        window death, a hard stop, the cap) is closed here, so every
+        `quota-wait-started` gets its `quota-wait-ended`."""
+        quota = _QuotaWait()
+        result = self._wait_loop(handle, spec, quota)
+        if quota.waiting:
+            self._end_quota_wait(handle, quota, "session-exit")
+        if quota.closed_s > 0:
+            result = dataclasses.replace(result, quota_wait_s=round(quota.closed_s, 3))
+        return result
+
+    def _wait_loop(
+        self, handle: SessionHandle, spec: SessionSpec, quota: _QuotaWait
+    ) -> SessionResult:
         deadline = time.monotonic() + spec.timeout_s
         # Wall-clock co-bound (#157): a host suspend freezes time.monotonic(),
         # silently extending the monotonic deadline by the nap's length. The
         # wall clock keeps counting through a suspend, so it may EXPIRE the
         # deadline — never extend it; all sub-waits below stay monotonic (a
-        # wall clock stepped backward must not stretch the session).
+        # wall clock stepped backward must not stretch the session). The one
+        # sanctioned exception is the usage-limit quota wait (DW-396), which
+        # re-bases BOTH deadlines on every tick; see the freeze below.
         wall_deadline = time.time() + spec.timeout_s
         session_id: str | None = None
         # Pinned to the launch-time id when the profile declared one (DW-505);
@@ -1260,6 +1320,14 @@ def wait_for_completion(self, handle: SessionHandle, spec: SessionSpec) -> Sessi
         # the stall wake nudge, which it withholds (the nudge's Enter can answer
         # the prompt, #727), ending the session `stalled` + `parked`.
         parked_evidence: str | None = None
+        # The canonical parked kind behind `parked_evidence` (`_parked_hook_kind`),
+        # latched and cleared with it: a QuotaPrompt/PermissionPrompt latch blocks
+        # or ends a usage-limit quota wait, an IdlePrompt one never does (DW-396).
+        parked_kind: str | None = None
+        # Whether this session can enter a usage-limit quota wait at all
+        # (DW-396): a cap and a profile that names the wait line. Off, the
+        # heartbeat stays byte-identical and nothing below is consulted.
+        quota_enabled = spec.quota_wait_max_s > 0 and bool(self._usage_wait_patterns)
         # the running streak of no-event ticks whose liveness probe raised a
         # transport error (e.g. a 30s tmux hang); reset by the next clean probe.
         # It deliberately does NOT escalate to "crashed" — a transient transport
@@ -1474,6 +1542,31 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
             # nudge arm so a tick that both sees growth and sends a nudge scores the
             # growth (the nudge cannot have caused what preceded it).
             sample_frame()
+            if quota.waiting:
+                # Usage-limit quota wait (DW-396): the CLI sits behind a usage
+                # window it will continue from by itself, so the session clock
+                # stands still. The cap is checked first, on the longer of the
+                # two clocks' spans (`_QuotaWait.open_s`), so a host suspend
+                # cannot stretch it; at the cap the session ends stalled + parked
+                # with the usage evidence, never completed (only a Stop or window
+                # death completes a session).
+                waited = quota.total_s()
+                if waited >= spec.quota_wait_max_s:
+                    self._note_quota_wait_cap(
+                        handle, quota.evidence, round(waited, 3), spec.quota_wait_max_s
+                    )
+                    evidence = quota.evidence
+                    self._end_quota_wait(handle, quota, "cap")
+                    return stall_exit(evidence, evidence)
+                # The freeze runs on EVERY tick, not only on heartbeats: a wait
+                # admitted with less than a heartbeat interval left would
+                # otherwise time out between samples. This is the one sanctioned
+                # exception to #157's "the wall clock may expire the deadline,
+                # never extend it": both deadlines are re-based to now plus the
+                # remaining time frozen at admission. The wait's own cap above
+                # is what bounds it.
+                deadline = time.monotonic() + quota.frozen_remaining
+                wall_deadline = time.time() + quota.frozen_remaining
             remaining = deadline - time.monotonic()
             wall_expired = time.time() >= wall_deadline
             if remaining <= 0 or wall_expired:
@@ -1557,6 +1650,46 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                 # has named the transcript.
                 if transcript_path:
                     sample_transcript(transcript_path, now)
+                if quota.waiting:
+                    # The transcript moved: the CLI continued after the reset.
+                    # The timeout resumes from the remaining time frozen at
+                    # admission. A pane that merely stopped matching does not
+                    # end the wait: the line can scroll away.
+                    if idle.idle_s is not None and idle.idle_s < QUOTA_WAIT_IDLE_S:
+                        self._end_quota_wait(handle, quota, "transcript-active")
+                elif (
+                    quota_enabled
+                    and transcript_path
+                    and idle.idle_s is not None
+                    and idle.idle_s >= QUOTA_WAIT_IDLE_S
+                    and parked_kind not in QUOTA_WAIT_BLOCKING_KINDS
+                    and quota.closed_s < spec.quota_wait_max_s
+                ):
+                    # Admission (DW-396): an idle transcript, the wait line on
+                    # the visible pane, and no unanswered tool call (a long
+                    # foreground tool is a working session, whatever the pane
+                    # still shows). The pane look comes first: it is the
+                    # cheaper read, and a non-match skips the transcript scan.
+                    (wait_hit,) = self._pane_evidence(handle, self._usage_wait_patterns)
+                    if wait_hit is not None and not self._quota_wait_tool_open(
+                        handle, transcript_path
+                    ):
+                        frozen = max(
+                            min(remaining, wall_deadline - time.time()),
+                            QUOTA_WAIT_MIN_REMAINING_S,
+                        )
+                        self._note_quota_wait_started(
+                            handle,
+                            wait_hit[0],
+                            round(frozen, 3),
+                            round(quota.closed_s, 3),
+                            spec.quota_wait_max_s,
+                        )
+                        quota.waiting = True
+                        quota.started_mono = time.monotonic()
+                        quota.started_wall = time.time()
+                        quota.frozen_remaining = frozen
+                        quota.evidence = wait_hit[0]
                 if not saw_session_start and not session_start_noted:
                     session_start_noted = self._note_session_start_missing(
                         handle, now - loop_started
@@ -1580,6 +1713,16 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                         "usage_sample_failures": usage_failures,
                         # hook events dropped as a nested CLI's (#767)
                         "foreign_hook_events": foreign_hook_events,
+                        # the usage-limit quota wait (DW-396): present only when
+                        # this session can enter one.
+                        **(
+                            {
+                                "quota_waiting": quota.waiting,
+                                "quota_wait_s": round(quota.total_s(), 3),
+                            }
+                            if quota_enabled
+                            else {}
+                        ),
                     },
                 )
                 # Mid-session spec-status transition sampling (#276 M2) rides the
@@ -1692,6 +1835,9 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                                 self._note_nudge_send_failed(handle, "budget", e)
                             budget_deadline = time.monotonic() + spec.token_budget_grace_s
                             budget_wall_deadline = time.time() + spec.token_budget_grace_s
+            # The token-budget grace is deliberately NOT frozen by a usage-limit
+            # quota wait (DW-396): a crossed budget is real spend, and a session
+            # waiting out a reset after crossing it has nothing left to earn.
             if budget_deadline is not None and (
                 time.monotonic() >= budget_deadline
                 or (budget_wall_deadline is not None and time.time() >= budget_wall_deadline)
@@ -1822,6 +1968,15 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                         stall_deadline = time.monotonic() + self._stall_grace_s
                         continue
                 if stall_deadline is not None and time.monotonic() >= stall_deadline:
+                    if quota.waiting:
+                        # Stall hold (DW-396): a CLI waiting out a usage-window
+                        # reset is silent by design, and a nudge typed into it
+                        # can only reproduce the limit line. Re-arm the grace,
+                        # spend nothing. A QuotaPrompt/PermissionPrompt latch has
+                        # already ended the wait, so it still parks here.
+                        stall_deadline = time.monotonic() + self._stall_grace_s
+                        last_activity = self._log_activity_key(handle.task_id)
+                        continue
                     # The cap bounds ATTEMPTS, delivered or not (DW-449).
                     nudge_due = stall_nudges_left > 0 and (
                         spec.stall_nudges_cap is None
@@ -2011,12 +2166,19 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                 evidence = self._parked_hook_evidence(event.event, event.notification_type)
                 if evidence is not None:
                     parked_evidence = evidence
+                    parked_kind = self._parked_hook_kind(event.event, event.notification_type)
                     self._note_lifecycle(handle.task_id, "parked-signal", evidence=evidence)
+                    # A CLI now asking a human is no longer waiting on a reset
+                    # (DW-396): end the wait; the next stall expiry parks it.
+                    # An IdlePrompt never ends one.
+                    if quota.waiting and parked_kind in QUOTA_WAIT_BLOCKING_KINDS:
+                        self._end_quota_wait(handle, quota, "latch")
                 continue
             if event.event == "Stop":
                 # A completed turn proves any prompt the CLI was parked on got
                 # answered: drop the parked latch before anything else (DW-348).
                 parked_evidence = None
+                parked_kind = None
                 # A turn ENDED — the one canonical event that proves the CLI did
                 # something, and so the hook half of the #261 proof-of-work gate.
                 # Latched after the subagent filter above, which rejects a stop that
@@ -2047,6 +2209,17 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                         budget_weighted=budget_weighted,
                         stop_seen=stop_seen,
                     )
+                if quota.waiting:
+                    # A result-less Stop while the CLI waits out a usage-window
+                    # reset (DW-396): typing the stop nudge into it can only
+                    # reproduce the limit line. Withhold it and keep waiting.
+                    self._note_lifecycle(
+                        handle.task_id,
+                        "stop-nudge-withheld",
+                        reason="quota-wait",
+                        nudge_due=nudges_left > 0,
+                    )
+                    continue
                 if nudges_left > 0:
                     nudges_left -= 1
                     try:
@@ -2426,6 +2599,108 @@ def _parked_hook_evidence(self, kind: str, notification_type: str | None) -> str
             return None
         return f"Notification({notification_type}) -> {mapped}"
 
+    def _parked_hook_kind(self, kind: str, notification_type: str | None) -> str | None:
+        """The canonical parked kind behind `_parked_hook_evidence`'s evidence:
+        the kind itself, or the one the profile maps a `Notification` subtype
+        to. None exactly when that evidence is None."""
+        if kind in PARKED_EVENTS:
+            return kind
+        if kind != "Notification" or notification_type is None:
+            return None
+        return self.profile.hooks.notification_types.get(notification_type)
+
+    def _quota_wait_tool_open(self, handle: SessionHandle, transcript_path: str) -> bool:
+        """Whether an unanswered tool call blocks a usage-limit quota wait
+        (DW-396): `_open_tool_call` over the transcript and its subagent tree.
+        A CLI blocked on a foreground tool is working, whatever its pane still
+        shows. Only `claude-jsonl` has the tool_use/tool_result shape; other
+        parsers cannot tell and read as "none open". A read fault refuses the
+        wait (a scan that cannot tell must not freeze the clock), crumbed as
+        `quota-wait-tool-scan-failed`."""
+        if self.profile.usage_parser != "claude-jsonl":
+            return False
+        try:
+            paths = [Path(transcript_path)]
+            root = self._subagent_root(transcript_path)
+            if root is not None:
+                paths.extend(path for path, _ in _subagent_tree_files(root))
+            return self._open_tool_call(paths) is not None
+        except OSError as e:
+            self._note_lifecycle(
+                handle.task_id, "quota-wait-tool-scan-failed", error=f"{type(e).__name__}: {e}"
+            )
+            return True
+
+    # The quota-wait records (DW-396): a lifecycle crumb each, plus, best-effort,
+    # a run-journal event with `task_id` and measured fields alone (the pane
+    # evidence stays in the crumb), the `session-idle` pattern, so the TUI can
+    # read it. An unwritable journal must not end a session; the crumb keeps
+    # the record.
+
+    def _note_quota_wait_started(
+        self,
+        handle: SessionHandle,
+        evidence: str,
+        remaining_s: float,
+        waited_s: float,
+        cap_s: float,
+    ) -> None:
+        self._note_lifecycle(
+            handle.task_id,
+            "quota-wait-started",
+            evidence=evidence,
+            remaining_s=remaining_s,
+            waited_s=waited_s,
+            cap_s=cap_s,
+        )
+        if self.journal is None:
+            return
+        try:
+            self.journal.append(
+                "quota-wait-started",
+                task_id=handle.task_id,
+                remaining_s=remaining_s,
+                waited_s=waited_s,
+                cap_s=cap_s,
+            )
+        except OSError:
+            pass
+
+    def _note_quota_wait_cap(
+        self, handle: SessionHandle, evidence: str | None, waited_s: float, cap_s: float
+    ) -> None:
+        self._note_lifecycle(
+            handle.task_id, "quota-wait-cap", evidence=evidence, waited_s=waited_s, cap_s=cap_s
+        )
+        if self.journal is None:
+            return
+        try:
+            self.journal.append(
+                "quota-wait-cap", task_id=handle.task_id, waited_s=waited_s, cap_s=cap_s
+            )
+        except OSError:
+            pass
+
+    def _end_quota_wait(self, handle: SessionHandle, quota: _QuotaWait, how: str) -> None:
+        """Close an open quota wait: fold its length into `closed_s` and record
+        `quota-wait-ended` (`waited_s` = this wait, `total_s` = the session's,
+        `how` = `transcript-active` | `latch` | `cap` | `session-exit`)."""
+        waited = round(quota.open_s(), 3)
+        quota.closed_s += waited
+        quota.waiting = False
+        total = round(quota.closed_s, 3)
+        self._note_lifecycle(
+            handle.task_id, "quota-wait-ended", waited_s=waited, total_s=total, how=how
+        )
+        if self.journal is None:
+            return
+        try:
+            self.journal.append(
+                "quota-wait-ended", task_id=handle.task_id, waited_s=waited, total_s=total, how=how
+            )
+        except OSError:
+            pass
+
     @cached_property
     def _parked_prompt_patterns(self) -> tuple[regex.Pattern[str], ...]:
         """``profile.parked_prompt_patterns``, compiled once per adapter on first
@@ -3889,6 +4164,7 @@ def _post_kill_reconcile(
             timeout_expired_clock=result.timeout_expired_clock,
             budget_weighted=result.budget_weighted,
             stop_seen=result.stop_seen,
+            quota_wait_s=result.quota_wait_s,
         )
 
 
diff --git a/src/bmad_loop/data/settings/core.toml b/src/bmad_loop/data/settings/core.toml
index 8d1ca1cbb..c95897074 100644
--- a/src/bmad_loop/data/settings/core.toml
+++ b/src/bmad_loop/data/settings/core.toml
@@ -186,6 +186,12 @@ minimum = 0
 default_ref = "LimitsPolicy.workflow_stall_nudges_cap"
 description = "total (never-restored) stall nudges for an injected plugin-workflow session before it is called stalled; bounds a session that finished its work but never wrote its completion marker · 0 = stall on first grace expiry"
 [[section.field]]
+key = "quota_wait_max_min"
+kind = "int"
+minimum = 0
+default_ref = "LimitsPolicy.quota_wait_max_min"
+description = "cumulative minutes one session may sit in a usage-limit wait (the visible pane shows the coding CLI waiting out a usage-window reset it continues from by itself, and the transcript is idle) with its session timeout frozen and its stall nudge held · past the cap the session ends parked with usage-limit evidence · 0 = off (the timeout keeps counting through the wait)"
+[[section.field]]
 key = "dev_contract_nudge"
 kind = "switch"
 default_ref = "LimitsPolicy.dev_contract_nudge"
diff --git a/src/bmad_loop/engine.py b/src/bmad_loop/engine.py
index 967a2767e..a2fbf18d1 100644
--- a/src/bmad_loop/engine.py
+++ b/src/bmad_loop/engine.py
@@ -3080,6 +3080,8 @@ def _run_workflows(self, stage: str, task: StoryTask, seq: int) -> bool:
                     wf_extras["parked_evidence"] = result.parked_evidence
             if result.usage_limited:
                 wf_extras["usage_limited"] = result.usage_limited
+            if result.quota_wait_s > 0:
+                wf_extras["quota_wait_s"] = round(result.quota_wait_s, 1)
             self.journal.append(
                 "workflow-end",
                 plugin=lp.name,
@@ -8391,6 +8393,10 @@ def _session_end_extras(self, result: SessionResult, usage: TokenUsage | None =
         # verdict from the token veto.
         if result.usage_limited:
             extras["usage_limited"] = result.usage_limited
+        # usage-limit quota wait (DW-396): present-only — the seconds the session
+        # sat behind a usage-window reset with its timeout frozen.
+        if result.quota_wait_s > 0:
+            extras["quota_wait_s"] = round(result.quota_wait_s, 1)
         # empty read-back diagnosis (#780): same present-only convention. The
         # last resultless-stop verdict lands here because nothing reads the
         # crumb file, so a spec nested out of the read-back's reach timed out
@@ -8630,6 +8636,9 @@ def _run_session(
             token_budget_mode=self.policy.limits.session_budget_mode,
             token_budget_grace_s=float(self.policy.limits.session_budget_grace_s),
             cache_read_weight=self.policy.limits.cache_read_weight,
+            # usage-limit quota wait cap (DW-396): the timeout freezes while the
+            # CLI waits out a usage-window reset, for at most this long in total.
+            quota_wait_max_s=float(self.policy.limits.quota_wait_max_min * 60),
             # Launch-state snapshot of a review session's spec (#276 M1); None for
             # every other session and on a crash-resume (process-transient).
             spec_snapshot=spec_snapshot,
diff --git a/src/bmad_loop/policy.py b/src/bmad_loop/policy.py
index 525aa23fb..63df65e22 100644
--- a/src/bmad_loop/policy.py
+++ b/src/bmad_loop/policy.py
@@ -154,6 +154,13 @@ class LimitsPolicy:
     # after this many total nudges (non-blocking workflows then advance the
     # phase).
     workflow_stall_nudges_cap: int = 3
+    # cap on the cumulative minutes one session may sit in a usage-limit wait
+    # (SessionSpec.quota_wait_max_s): while the visible pane shows the CLI
+    # waiting out a usage-window reset it will continue from by itself, and the
+    # transcript is idle, the session timeout is frozen and the stall nudge is
+    # held (DW-396). Past the cap the session ends parked with usage-limit
+    # evidence. 0 = off (the timeout keeps counting through the wait).
+    quota_wait_max_min: int = 300
     # One targeted nudge per session (#276 M4) when a Stop finds a marker-less
     # terminal-frontmatter spec (a review that finalized `status: done`/`blocked`
     # without appending its required `## Auto Run Result` section): ask the skill
@@ -1018,6 +1025,9 @@ def loads(text: str, plugin_schemas: dict[str, Any] | None = None) -> Policy:
         workflow_stall_nudges_cap=_typed_int(
             limits_d, "limits", "workflow_stall_nudges_cap", LimitsPolicy.workflow_stall_nudges_cap
         ),
+        quota_wait_max_min=_typed_int(
+            limits_d, "limits", "quota_wait_max_min", LimitsPolicy.quota_wait_max_min
+        ),
         dev_contract_nudge=_typed_bool(
             limits_d, "limits", "dev_contract_nudge", LimitsPolicy.dev_contract_nudge
         ),
@@ -1084,6 +1094,10 @@ def loads(text: str, plugin_schemas: dict[str, Any] | None = None) -> Policy:
         raise PolicyError(
             f"limits.workflow_stall_nudges_cap must be >= 0: got {limits.workflow_stall_nudges_cap}"
         )
+    if limits.quota_wait_max_min < 0:
+        raise PolicyError(
+            f"limits.quota_wait_max_min must be >= 0: got {limits.quota_wait_max_min}"
+        )
     if limits.session_budget_mode not in SESSION_BUDGET_MODES:
         raise PolicyError(
             f"limits.session_budget_mode must be one of {sorted(SESSION_BUDGET_MODES)}: "
@@ -1513,6 +1527,7 @@ def _fold_deprecated_engine(
 dev_stall_nudges = 2         # best-effort wake nudges per silent grace before stalling; fresh Stop/idle evidence restores this budget. 0 = stall on grace expiry
 dev_stall_nudges_cap = 6     # total (never-restored) nudge bound per dev/review session; bounds launch-time recovery and Stop/idle budget refills because an accepted nudge does not guarantee a wake. 0 = stall on first grace expiry
 workflow_stall_nudges_cap = 3 # total (never-restored) stall nudges for an injected plugin-workflow session before it is called stalled; bounds a session that finished its work but never wrote its completion marker. 0 = stall on first grace expiry
+quota_wait_max_min = 300     # cumulative minutes one session may wait out a usage-window reset (pane shows the CLI's wait line, transcript idle) with its timeout frozen and stall nudge held; past it the session ends parked. 0 = off
 dev_contract_nudge = true    # true: one targeted nudge per session (#276) when a Stop finds a spec finalized to a terminal frontmatter status but missing its `## Auto Run Result` marker, asking the skill to append it and end its turn; sent exactly once, never refilled, touches no stall counters. false: rely only on harness-side frontmatter synthesis
 max_tokens_per_story = 2000000
 cache_read_weight = 0.1      # cache reads bill at ~0.1x input on all vendors; 1.0 = count raw
diff --git a/tests/test_engine.py b/tests/test_engine.py
index 0e5f0ba3e..ffbdcb49a 100644
--- a/tests/test_engine.py
+++ b/tests/test_engine.py
@@ -15380,6 +15380,27 @@ def test_usage_limited_session_end_is_journaled_and_paused(project):
     assert "usage_limited" not in plain_end
 
 
+def test_session_end_carries_quota_wait_s_only_when_positive(project):
+    """DW-396: the engine hands every session it drives the quota-wait cap
+    (`limits.quota_wait_max_min * 60`), and `session-end` carries the seconds the
+    session spent in a usage-limit quota wait only when it waited at all
+    (present-only).
+    ABLATION: drop the `quota_wait_s` extras line from `_session_end_extras` and
+    the first session-end assertion fails."""
+    write_sprint(project, {"1-1-a": "ready-for-dev"})
+    engine, adapter = make_engine(project, [SessionResult(status="stalled", quota_wait_s=480.0)])
+    engine.run()
+    assert adapter.sessions[0].quota_wait_max_s == 300 * 60.0
+    # The stall is retried: the FIRST session-end is the session that waited.
+    end = [e for e in engine.journal.entries() if e["kind"] == "session-end"][0]
+    assert end["quota_wait_s"] == 480.0
+    # The journal is per-project, so only the second run's own last entry counts.
+    engine2, _ = make_engine(project, [SessionResult(status="stalled")])
+    engine2.run()
+    plain_end = [e for e in engine2.journal.entries() if e["kind"] == "session-end"][-1]
+    assert "quota_wait_s" not in plain_end
+
+
 def test_session_env_fault_pauses_dev_without_burning_budget(project):
     """A dev session classified an environment fault (#194) pauses the run at the
     first story rather than charging the attempt; the decision + session-end carry
diff --git a/tests/test_generic_tmux.py b/tests/test_generic_tmux.py
index 9dd06fb32..cce3126df 100644
--- a/tests/test_generic_tmux.py
+++ b/tests/test_generic_tmux.py
@@ -12683,6 +12683,456 @@ def make_spec(halt: bool) -> SessionSpec:
     )
 
 
+# ------------------------------------------ usage-limit quota wait (DW-396)
+#
+# Claude Code behind a session-window limit waits for the reset and continues by
+# itself, repainting its pane the whole time, so the stall timer never fires
+# while `session_timeout_min` keeps counting. While the visible pane shows the
+# wait line and the transcript is idle, the session timeout is frozen and the
+# stall nudge held; transcript movement ends the wait; the cap ends the session
+# stalled + parked with the usage evidence. Never a completion path.
+
+QUOTA_SCREEN = f"\x1b[2m{USAGE_SESSION_LINE}\x1b[0m\r\n\r\n❯ \r\n"
+
+
+class _Quota:
+    """One quota-wait fixture: the adapter and every handle a test steers."""
+
+    def __init__(self, adapter, mux, impl, log, transcript, clock, heartbeats):
+        self.adapter = adapter
+        self.mux = mux
+        self.impl = impl
+        self.log = log
+        self.transcript = transcript
+        self.clock = clock
+        self.heartbeats = heartbeats
+
+    def wait_evidence(self) -> str:
+        pattern = self.adapter.profile.usage_wait_patterns[0]
+        return f"pane matched {pattern!r}: {USAGE_SESSION_LINE.strip()}"
+
+    def quota_kinds(self) -> list[str]:
+        return [e["kind"] for e in self.adapter.journal.entries if e["kind"].startswith("quota-")]
+
+    def finish_spec(self) -> None:
+        """The skill's terminal spec, so the next Stop completes the session."""
+        (self.impl / "spec-3-1-foo.md").write_text(
+            "---\nstatus: done\n---\n\n## Auto Run Result\n\nStatus: done\n",
+            encoding="utf-8",
+            newline="",
+        )
+
+
+def _quota_adapter(tmp_path, monkeypatch, *, screen=QUOTA_SCREEN, grace=600.0):
+    """A claude dev adapter over a `_UnitMux` showing `screen`, a fake journal,
+    a pane log, a transcript, captured heartbeats and independently steerable
+    monotonic/wall clocks."""
+    monkeypatch.setattr(generic, "RESULT_GRACE_S", 0.0)
+    monkeypatch.setattr(generic, "RESULT_POLL_S", 0.0)
+    mux = _UnitMux(screen=screen)
+    adapter, impl = make_dev_adapter(tmp_path, mux=mux)
+    adapter._stall_grace_s = grace
+    adapter._idle_threshold_s = grace
+    adapter._window_alive = lambda handle: True
+    adapter.journal = _FakeJournal()
+    log = _pane_log(adapter, "3-1-dev-1", 0)
+    transcript = tmp_path / "transcript.jsonl"
+    transcript.write_bytes(b'{"type":"user"}\n')
+    clock = {"mono": 1000.0, "wall": 5000.0}
+
+    class _Clock:
+        monotonic = staticmethod(lambda: clock["mono"])
+        time = staticmethod(lambda: clock["wall"])
+        sleep = staticmethod(lambda *_: None)
+        time_ns = staticmethod(lambda: 0)
+
+    monkeypatch.setattr(generic, "time", _Clock)
+    heartbeats: list[dict] = []
+    adapter._write_heartbeat = lambda task_id, payload: heartbeats.append(payload)
+    return _Quota(adapter, mux, impl, log, transcript, clock, heartbeats)
+
+
+def _quota_spec(tmp_path, *, timeout_s=300.0, cap_s=3600.0) -> SessionSpec:
+    return dataclasses.replace(_dev_spec(tmp_path), timeout_s=timeout_s, quota_wait_max_s=cap_s)
+
+
+def _drive_quota(q, spec, *, events=None, script=None, step=None, repaint=True, max_calls=500):
+    """Call 1 answers a SessionStart naming the transcript (the idle baseline at
+    mono 1000). Every later call first advances both clocks by `step(call_n)`
+    (default: one heartbeat interval), repaints the pane when `repaint` (the
+    countdown keeps the stall re-arm firing, as in the field), runs
+    `script(call_n)`, then answers `events[call_n]` or None. A loop that outlives
+    `max_calls` fails the test instead of hanging it.
+
+    The admission timeline every test below shares: heartbeats land at mono
+    1000 (no transcript yet), 1030, 1060 and 1090; the 1090 one (iteration 5)
+    reads 90 s of idle and admits the wait."""
+    events = dict(events or {})
+    events.setdefault(1, _session_start("3-1-dev-1", str(q.transcript)))
+
+    def on_call(call_n):
+        if call_n > max_calls:
+            raise AssertionError(f"wait loop still running after {max_calls} ticks")
+        if call_n >= 2:
+            dt = step(call_n) if step is not None else generic.HEARTBEAT_INTERVAL_S
+            q.clock["mono"] += dt
+            q.clock["wall"] += dt
+            if repaint:
+                _grow(q.log, "\r⠋".encode())
+        if script is not None:
+            script(call_n)
+
+    class _Watcher:
+        calls = 0
+
+        def wait_for(self, task_id, kinds, timeout_s, since_ns=0):
+            self.calls += 1
+            on_call(self.calls)
+            return events.get(self.calls)
+
+    q.adapter.watcher = _Watcher()
+    return q.adapter.wait_for_completion(_dev_handle(), spec)
+
+
+def _assistant_line() -> bytes:
+    return b'{"type":"assistant","message":{"content":[{"type":"text","text":"ok"}]}}\n'
+
+
+def test_quota_wait_freezes_the_session_timeout(tmp_path, monkeypatch):
+    """The DW-396 incident, end to end: a 300 s session sits behind the session
+    limit from mono 1090 (210 s left) until the CLI continues at 1570, well past
+    the original deadline (1300). The frozen timeout does not fire; the
+    transcript moving ends the wait (`transcript-active`) and the session
+    completes on its Stop, carrying the 480 s it waited.
+
+    Ablation: drop the per-tick freeze and this times out at mono 1300."""
+    q = _quota_adapter(tmp_path, monkeypatch)
+
+    def script(call_n):
+        if call_n == 20:
+            _grow(q.transcript, _assistant_line())  # the reset passed: it continued
+        if call_n == 21:
+            q.finish_spec()
+
+    result = _drive_quota(
+        q,
+        _quota_spec(tmp_path),
+        events={21: _stop_event("3-1-dev-1", "sess", str(q.transcript))},
+        script=script,
+    )
+    assert result.status == "completed"
+    assert result.quota_wait_s == 480.0  # mono 1090 → 1570
+    assert result.usage_limited is None  # it continued: not a usage-limited verdict
+    assert q.mux.sent == []
+    assert _lifecycle_events(q.adapter, "timeout-fired") == []
+    assert q.quota_kinds() == ["quota-wait-started", "quota-wait-ended"]
+    started, ended = (e for e in q.adapter.journal.entries if e["kind"].startswith("quota-"))
+    assert started == {
+        "kind": "quota-wait-started",
+        "task_id": "3-1-dev-1",
+        "remaining_s": 210.0,
+        "waited_s": 0.0,
+        "cap_s": 3600.0,
+    }
+    assert ended == {
+        "kind": "quota-wait-ended",
+        "task_id": "3-1-dev-1",
+        "waited_s": 480.0,
+        "total_s": 480.0,
+        "how": "transcript-active",
+    }
+    (crumb,) = _lifecycle_events(q.adapter, "quota-wait-started")
+    assert crumb["evidence"] == q.wait_evidence()  # the pane line stays in the crumb
+
+
+def test_quota_wait_freezes_on_every_tick_not_only_heartbeats(tmp_path, monkeypatch):
+    """A wait admitted with 30 s left (under one heartbeat interval), then 5 s
+    ticks: the freeze must re-base the deadline on EVERY tick. One applied only on
+    heartbeats would leave the admission tick's deadline (mono 1120) standing
+    until the next heartbeat, which the timeout check at mono 1120 reaches
+    first. Here the wait runs on to its 200 s cap instead: stalled + parked, no
+    timeout.
+
+    Ablation: drop the per-tick freeze and this times out at mono 1120."""
+    q = _quota_adapter(tmp_path, monkeypatch)
+    result = _drive_quota(
+        q,
+        _quota_spec(tmp_path, timeout_s=120.0, cap_s=200.0),
+        step=lambda call_n: generic.HEARTBEAT_INTERVAL_S if call_n <= 4 else 5.0,
+    )
+    assert _lifecycle_events(q.adapter, "timeout-fired") == []
+    assert (result.status, result.parked) == ("stalled", True)
+    (started,) = _lifecycle_events(q.adapter, "quota-wait-started")
+    assert started["remaining_s"] == generic.QUOTA_WAIT_MIN_REMAINING_S  # 30 s, floored
+
+
+def test_quota_wait_needs_an_idle_transcript(tmp_path, monkeypatch):
+    """The wait line on screen but a transcript still being written (a session
+    that recovered and kept working, the line still on screen): no wait, and the
+    timeout fires on schedule.
+
+    Ablation: drop the `idle_s >= QUOTA_WAIT_IDLE_S` guard and a wait opens at
+    the first heartbeat."""
+    q = _quota_adapter(tmp_path, monkeypatch)
+
+    def script(call_n):
+        if call_n >= 2:
+            _grow(q.transcript, _assistant_line())
+
+    result = _drive_quota(q, _quota_spec(tmp_path), script=script)
+    assert result.status == "timeout"
+    assert result.quota_wait_s == 0.0
+    assert q.quota_kinds() == []
+    assert _lifecycle_events(q.adapter, "quota-wait-started") == []
+
+
+def test_quota_wait_not_admitted_with_an_open_tool_call(tmp_path, monkeypatch):
+    """An idle transcript whose last line opens a `Bash` call: the CLI is waiting
+    on its own foreground tool, not on a reset, whatever the pane still shows.
+    No wait; the timeout fires on schedule.
+
+    Ablation: drop the `_quota_wait_tool_open` guard and the wait opens."""
+    q = _quota_adapter(tmp_path, monkeypatch)
+    _grow(q.transcript, _tool_use("t1", "Bash", "2026-01-01T00:00:01Z"))
+    result = _drive_quota(q, _quota_spec(tmp_path))
+    assert result.status == "timeout"
+    assert result.quota_wait_s == 0.0
+    assert q.quota_kinds() == []
+
+
+def test_quota_wait_off_when_cap_is_zero(tmp_path, monkeypatch):
+    """`quota_wait_max_s = 0` (the raw SessionSpec default; the engine passes
+    `limits.quota_wait_max_min * 60`): today's behaviour. The timeout fires on
+    schedule, nothing is captured for admission (the one capture is the
+    timeout-fired path's), and the heartbeat carries no quota fields."""
+    q = _quota_adapter(tmp_path, monkeypatch)
+    result = _drive_quota(q, _quota_spec(tmp_path, cap_s=0.0))
+    assert result.status == "timeout"
+    assert result.usage_limited == q.wait_evidence()  # S1's look at the timeout
+    assert q.mux.captures == ["@1"]
+    assert q.quota_kinds() == []
+    assert all("quota_waiting" not in hb and "quota_wait_s" not in hb for hb in q.heartbeats)
+
+
+@pytest.mark.parametrize("clock_kind", ["monotonic", "wall-suspend"])
+def test_quota_wait_cap_ends_parked_with_usage_evidence(tmp_path, monkeypatch, clock_kind):
+    """A reset that never comes: at the 600 s cap the session ends stalled +
+    parked with the wait line as both evidences, never completed and never
+    `timeout`. The cap is bounded on BOTH clocks: in the suspend variant the
+    monotonic clock barely moves after admission while the wall clock jumps an
+    hour, and the cap still fires on the wall span.
+
+    Ablation: measure the open wait on the monotonic clock alone and the suspend
+    variant never reaches its cap (the max_calls guard fails it)."""
+    q = _quota_adapter(tmp_path, monkeypatch)
+
+    def step(call_n):
+        if call_n <= 4 or clock_kind == "monotonic":
+            return generic.HEARTBEAT_INTERVAL_S
+        return 0.0
+
+    def script(call_n):
+        if clock_kind == "wall-suspend" and call_n == 8:
+            q.clock["wall"] += 3600.0  # host suspend: monotonic frozen, wall runs
+
+    result = _drive_quota(q, _quota_spec(tmp_path, cap_s=600.0), step=step, script=script)
+    assert (result.status, result.parked) == ("stalled", True)
+    assert result.parked_evidence == result.usage_limited == q.wait_evidence()
+    assert result.result_json is None
+    assert result.quota_wait_s >= 600.0
+    assert _lifecycle_events(q.adapter, "timeout-fired") == []
+    (cap,) = _lifecycle_events(q.adapter, "quota-wait-cap")
+    assert cap["evidence"] == q.wait_evidence()
+    assert cap["cap_s"] == 600.0 and cap["waited_s"] >= 600.0
+    assert q.quota_kinds() == ["quota-wait-started", "quota-wait-cap", "quota-wait-ended"]
+    assert q.adapter.journal.entries[-1]["how"] == "cap"
+
+
+def test_quota_wait_holds_the_stall_nudge(tmp_path, monkeypatch):
+    """A silent pane (no repaint) and a 120 s grace with nudges available: once
+    the wait is admitted (mono 1090), every grace expiry re-arms with no nudge and
+    no park, until the CLI continues and Stops with its result.
+
+    Ablation: drop the stall hold and the 1120 expiry parks the session through
+    S1's usage gate."""
+    q = _quota_adapter(tmp_path, monkeypatch, grace=120.0)
+    q.adapter._stall_nudges = 2
+
+    def script(call_n):
+        if call_n == 30:
+            _grow(q.transcript, _assistant_line())
+        if call_n == 31:
+            q.finish_spec()
+
+    result = _drive_quota(
+        q,
+        _quota_spec(tmp_path),
+        events={31: _stop_event("3-1-dev-1", "sess", str(q.transcript))},
+        script=script,
+        repaint=False,
+    )
+    assert result.status == "completed"
+    assert _stall_nudges(q.mux) == []
+    assert _lifecycle_events(q.adapter, "stall-nudge-withheld") == []
+    assert result.quota_wait_s > 0
+
+
+@pytest.mark.parametrize(
+    ("subtype", "evidence"),
+    [
+        ("permission_prompt", "Notification(permission_prompt) -> PermissionPrompt"),
+        ("quota_auto_resume_stale", "Notification(quota_auto_resume_stale) -> QuotaPrompt"),
+    ],
+)
+def test_quota_prompt_latch_ends_the_wait_parked(tmp_path, monkeypatch, subtype, evidence):
+    """A CLI that, mid-wait, asks a human for a permission or quota decision is
+    no longer going to continue by itself: the latch ends the wait (`latch`) and
+    the next stall expiry parks the session on the latch's evidence.
+
+    Ablation: drop the latch exit and the session waits on to its cap."""
+    q = _quota_adapter(tmp_path, monkeypatch, grace=120.0)
+    result = _drive_quota(
+        q,
+        _quota_spec(tmp_path, cap_s=3600.0),
+        events={7: _hook_event("Notification", subtype)},
+        repaint=False,
+    )
+    assert (result.status, result.parked) == ("stalled", True)
+    assert result.parked_evidence == evidence
+    assert q.mux.sent == []
+    (ended,) = (e for e in q.adapter.journal.entries if e["kind"] == "quota-wait-ended")
+    assert ended["how"] == "latch"
+    assert _lifecycle_events(q.adapter, "quota-wait-cap") == []
+
+
+def test_idle_prompt_latch_does_not_end_the_wait(tmp_path, monkeypatch):
+    """claude sends `idle_prompt` ~60 s after every finished turn, including the
+    one the limit ended: that latch never ends a wait, so the held stall
+    expiries keep holding and the session completes once the CLI continues.
+
+    Ablation: count IdlePrompt among QUOTA_WAIT_BLOCKING_KINDS and the next
+    expiry parks the session."""
+    q = _quota_adapter(tmp_path, monkeypatch, grace=120.0)
+
+    def script(call_n):
+        if call_n == 30:
+            _grow(q.transcript, _assistant_line())
+        if call_n == 31:
+            q.finish_spec()
+
+    result = _drive_quota(
+        q,
+        _quota_spec(tmp_path),
+        events={
+            7: _hook_event("Notification", "idle_prompt"),
+            31: _stop_event("3-1-dev-1", "sess", str(q.transcript)),
+        },
+        script=script,
+        repaint=False,
+    )
+    assert result.status == "completed"
+    assert result.parked is False
+    ended = [e for e in q.adapter.journal.entries if e["kind"] == "quota-wait-ended"]
+    assert [e["how"] for e in ended] == ["transcript-active"]
+
+
+def test_stop_without_result_during_quota_wait_withholds_the_stop_nudge(tmp_path, monkeypatch):
+    """A result-less Stop mid-wait: the stop nudge is withheld (it could only
+    reproduce the limit line), crumbed `stop-nudge-withheld` with
+    `reason="quota-wait"`, and the wait goes on. A later Stop WITH a result
+    completes normally.
+
+    Ablation: drop the quota-wait branch in the Stop handler and NUDGE_TEXT is
+    sent."""
+    q = _quota_adapter(tmp_path, monkeypatch)
+    q.adapter._stop_nudges = 1
+
+    def script(call_n):
+        if call_n == 20:
+            _grow(q.transcript, _assistant_line())
+        if call_n == 21:
+            q.finish_spec()
+
+    result = _drive_quota(
+        q,
+        _quota_spec(tmp_path),
+        events={
+            8: _stop_event("3-1-dev-1", "sess", str(q.transcript)),
+            21: _stop_event("3-1-dev-1", "sess", str(q.transcript)),
+        },
+        script=script,
+    )
+    assert result.status == "completed"
+    assert [text for _, text in q.mux.sent if text == generic.NUDGE_TEXT] == []
+    (withheld,) = _lifecycle_events(q.adapter, "stop-nudge-withheld")
+    assert withheld["reason"] == "quota-wait"
+    assert withheld["nudge_due"] is True
+    assert q.quota_kinds() == ["quota-wait-started", "quota-wait-ended"]
+
+
+def test_pane_non_match_does_not_end_the_wait(tmp_path, monkeypatch):
+    """The wait line scrolls off the visible pane mid-wait: that alone does not
+    end the wait (the timeout stays frozen past the original deadline); only the
+    transcript moving does."""
+    q = _quota_adapter(tmp_path, monkeypatch)
+
+    def script(call_n):
+        if call_n == 6:
+            q.mux.screen = "❯ \r\n"  # the line scrolled away
+        if call_n == 20:
+            _grow(q.transcript, _assistant_line())
+        if call_n == 21:
+            q.finish_spec()
+
+    result = _drive_quota(
+        q,
+        _quota_spec(tmp_path),
+        events={21: _stop_event("3-1-dev-1", "sess", str(q.transcript))},
+        script=script,
+    )
+    assert result.status == "completed"
+    assert result.quota_wait_s == 480.0
+    ended = [e for e in q.adapter.journal.entries if e["kind"] == "quota-wait-ended"]
+    assert [e["how"] for e in ended] == ["transcript-active"]
+
+
+def test_heartbeat_carries_quota_wait_fields(tmp_path, monkeypatch):
+    """`heartbeat.json` carries `quota_waiting` and `quota_wait_s` whenever the
+    session can wait: False / 0.0 before admission, True and climbing during the
+    wait (the frozen `remaining_s` holding still), False again after it with the
+    cumulative total kept, while the resumed timeout counts down from the frozen
+    210 s to its fire."""
+    q = _quota_adapter(tmp_path, monkeypatch)
+
+    def script(call_n):
+        if call_n >= 8:
+            _grow(q.transcript, _assistant_line())  # continued, and keeps working
+
+    result = _drive_quota(q, _quota_spec(tmp_path), script=script)
+    assert result.status == "timeout"  # the resumed deadline: mono 1210 + 210
+    fields = [(hb["quota_waiting"], hb["quota_wait_s"]) for hb in q.heartbeats]
+    # heartbeats at mono 1000, 1030, 1060, 1090 (admitted inside this one, ahead
+    # of the write), 1120, 1150, 1180, 1210 (the transcript moved: ended), 1240…
+    assert fields[:3] == [(False, 0.0)] * 3
+    assert fields[3] == (True, 0.0)
+    assert fields[4:7] == [(True, 30.0), (True, 60.0), (True, 90.0)]
+    assert set(fields[7:]) == {(False, 120.0)}
+    assert [hb["remaining_s"] for hb in q.heartbeats[3:]] == [
+        210.0,
+        210.0,
+        210.0,
+        210.0,
+        210.0,
+        180.0,
+        150.0,
+        120.0,
+        90.0,
+        60.0,
+        30.0,
+    ]
+    assert result.quota_wait_s == 120.0
+
+
 # ------------------------------- session-start-missing notice
 #
 # Observation only. A session whose profile maps SessionStart but that has run
diff --git a/tests/test_policy.py b/tests/test_policy.py
index 60f6733b4..5c97e6d40 100644
--- a/tests/test_policy.py
+++ b/tests/test_policy.py
@@ -682,6 +682,19 @@ def test_dev_stall_nudges_cap_default_parse_and_template():
         policy.loads("[limits]\ndev_stall_nudges_cap = -1\n")
 
 
+def test_quota_wait_max_min_default_parse_and_template():
+    import tomllib
+
+    assert policy.loads("").limits.quota_wait_max_min == 300
+    loaded = policy.loads("[limits]\nquota_wait_max_min = 0\n")
+    assert loaded.limits.quota_wait_max_min == 0  # 0 = off
+    # the emitted template documents the knob at its dataclass default
+    doc = tomllib.loads(policy.POLICY_TEMPLATE)
+    assert doc["limits"]["quota_wait_max_min"] == policy.LimitsPolicy.quota_wait_max_min
+    with pytest.raises(policy.PolicyError, match="quota_wait_max_min"):
+        policy.loads("[limits]\nquota_wait_max_min = -1\n")
+
+
 def test_dev_contract_nudge_default_parse_and_template():
     import tomllib
 
diff --git a/tests/test_portability_guard.py b/tests/test_portability_guard.py
index e8929d705..cfe9f208e 100644
--- a/tests/test_portability_guard.py
+++ b/tests/test_portability_guard.py
@@ -654,6 +654,9 @@
         "cache_read_weight",
         "cache_read_weight_was",
         "cap",
+        # `quota-wait-started` / `quota-wait-cap` (DW-396): the session's quota
+        # wait cap in seconds (`SessionSpec.quota_wait_max_s`) — a measured float.
+        "cap_s",
         "checkout_dirty",
         "checkpoint",
         "code_root_changed",
@@ -767,6 +770,9 @@
         "grace_s",
         "graceful",
         "harvest_attempt",
+        # `quota-wait-ended` (DW-396): what ended the wait, a closed slug the
+        # adapter chose (`transcript-active` / `latch` / `cap` / `session-exit`).
+        "how",
         # `head` is NOT here any more: a HEAD sha (`attempt-preserve-failed`,
         # `attempt-preserve-fallthrough`) moved to `_JOURNAL_ALIAS_FIELDS` (DW-481).
         "id_collisions",
@@ -944,6 +950,9 @@
         # exists to draw. Names no path, identifier or prose.
         "regen_cause",
         "remaining",
+        # `quota-wait-started` (DW-396): the session-timeout seconds the wait
+        # froze — a measured float.
+        "remaining_s",
         # DW-525: run ids (the `run_id` shape) — the finished run a replay run
         # replays (`unit-replay-start`) and the replay run a finished run handed its
         # kept unit to (`unit-replay-handoff`).
@@ -1007,11 +1016,17 @@
         "tokens",
         "tokens_weighted",
         "total",
+        # `quota-wait-ended` (DW-396): the session's cumulative quota-wait
+        # seconds — a measured float.
+        "total_s",
         "trigger",
         # `session-end` / `workflow-end` (#610): the visible-pane line a usage-limit
         # pattern matched live — the matched profile pattern plus the quoted pane
         # line, the same class of excerpt as `parked_evidence`.
         "usage_limited",
+        # `session-end` / `workflow-end` (DW-396): the seconds the session sat in a
+        # usage-limit quota wait with its timeout frozen — a measured float.
+        "quota_wait_s",
         "verification_sequence",
         "verification_stage",
         "via",
@@ -1190,6 +1205,7 @@
             "parked",
             "parked_evidence",
             "usage_limited",
+            "quota_wait_s",
         }
     ),
     # The plugin bus's `_log` forwards its OWN `**fields` parameter, so the keys
@@ -1340,6 +1356,15 @@
         # `in_tool`, a closed slug the adapter chose (declared benign).
         "session-active",
         "session-idle",
+        # The usage-limit quota wait (DW-396): `quota-wait-started` when a session
+        # behind a usage-window reset has its timeout frozen, `quota-wait-ended`
+        # when the wait closes, `quota-wait-cap` when the cap ends the session.
+        # `task_id` (routed) and measured floats (`remaining_s`, `waited_s`,
+        # `total_s`, `cap_s`) plus the closed slug `how` (declared benign); the
+        # pane evidence stays in the lifecycle crumb.
+        "quota-wait-cap",
+        "quota-wait-ended",
+        "quota-wait-started",
         # One `session-start-missing` when a CLI whose profile maps SessionStart
         # has sent none by `limits.session_start_grace_s`: `task_id` (routed),
         # `waited_s`/`grace_s` (declared benign), `cli` and, on a Codex profile,

From 904418c6b75dc7b451705874861ae6141c398d80 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Sun, 25 Oct 2026 13:13:00 -0700
Subject: [PATCH 3/8] feat(adapters): parse the usage-limit reset time into
 pause reasons, the heartbeat and the TUI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A new pure module, usagereset.py (pyright-strict), parses the `resets …`
clause of a matched usage-limit pane line: `[<Weekday> | <Mon> <D> at
]H[:MM](am|pm)[ (<Area/City>)]`, resolved to the next occurrence after an
aware local now, in the named zone when one is given. It never raises: an
unknown zone (no tzdata) or shape keeps the raw text and is crumbed
`usage-reset-unparsed`.

The reset rides SessionResult.usage_limit_resets (appended last) from every
usage-limited exit (stall gate, timeout look, quota-wait cap), the pause
reason (`; resets <value>`), session-end / workflow-end (present-only),
heartbeat.json `quota_resets_at` while waiting, and quota-wait-started
`resets_at`. A resolved reset beyond the remaining cap skips the wait and ends
stalled + parked at once (crumb quota-wait-skipped, reason=reset-beyond-cap),
never a completion. The TUI header renders an open quota wait as
`quota wait <age> · resets <time>` instead of the idle notice.
---
 CHANGELOG.md                      |   4 +
 pyproject.toml                    |   1 +
 src/bmad_loop/adapters/base.py    |   6 +
 src/bmad_loop/adapters/generic.py |  93 ++++++++++++--
 src/bmad_loop/engine.py           |   6 +
 src/bmad_loop/escalation.py       |  10 +-
 src/bmad_loop/tui/data.py         |  48 +++++++
 src/bmad_loop/tui/widgets.py      |  29 ++++-
 src/bmad_loop/usagereset.py       | 141 ++++++++++++++++++++
 tests/test_engine.py              |  30 +++++
 tests/test_escalation.py          |  17 +++
 tests/test_generic_tmux.py        | 149 +++++++++++++++++++++-
 tests/test_portability_guard.py   |   7 +
 tests/test_tui_app.py             |  51 ++++++++
 tests/test_tui_data.py            |  57 +++++++++
 tests/test_usagereset.py          | 205 ++++++++++++++++++++++++++++++
 16 files changed, 838 insertions(+), 16 deletions(-)
 create mode 100644 src/bmad_loop/usagereset.py
 create mode 100644 tests/test_usagereset.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index de6d9c905..521a90c2f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,10 @@ breaking changes may land in a minor release.
   auto-continue. Past the cap the session pauses with a usage-limit reason.
   `heartbeat.json` gains `quota_waiting` / `quota_wait_s`, `session-end` gains
   `quota_wait_s`, and the journal gains `quota-wait-started` / `-ended` / `-cap`.
+  The line's `resets …` time is parsed into the pause reason (`; resets <time>`),
+  `heartbeat.json` (`quota_resets_at`), `session-end` (`usage_limit_resets`) and the
+  TUI header, which shows `quota wait` instead of `idle`. A reset beyond the remaining
+  cap skips the wait and pauses at once.
 - Add the experimental `tickets` work source for BMAD v7 initiative ticket trees
   (`[stories] source = "tickets"`): dispatch `bmad-build-auto ticket <ref>` in initiative
   build order, verify each plan at `built`, and mark it `done` through `tickets.py mark`
diff --git a/pyproject.toml b/pyproject.toml
index af155a0b1..8177f1792 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -150,6 +150,7 @@ strict = [
   "src/bmad_loop/worksource.py",
   "src/bmad_loop/ticketmodel.py",
   "src/bmad_loop/ticketstore.py",
+  "src/bmad_loop/usagereset.py",
 ]
 # Check against the floor of requires-python so we never lean on 3.12+ typing.
 pythonVersion = "3.11"
diff --git a/src/bmad_loop/adapters/base.py b/src/bmad_loop/adapters/base.py
index 1f0734874..f64bc2d57 100644
--- a/src/bmad_loop/adapters/base.py
+++ b/src/bmad_loop/adapters/base.py
@@ -366,6 +366,12 @@ class SessionResult:
     # result `wait_for_completion` returns, journaled on `session-end` only when
     # positive. APPENDED.
     quota_wait_s: float = 0.0
+    # The usage limit's reset (#610), parsed from the same live pane line as
+    # `usage_limited` (`usagereset.parse_reset`): ISO-8601 when resolved, else
+    # the raw clause text (an unknown zone, an unknown shape — crumbed as
+    # `usage-reset-unparsed`). None = no `resets` clause on the line, or not
+    # usage-limited. Named by the pause reason; journaled present-only. APPENDED.
+    usage_limit_resets: str | None = None
 
 
 class CodingCLIAdapter(ABC):
diff --git a/src/bmad_loop/adapters/generic.py b/src/bmad_loop/adapters/generic.py
index 21886af9a..29291f892 100644
--- a/src/bmad_loop/adapters/generic.py
+++ b/src/bmad_loop/adapters/generic.py
@@ -37,6 +37,7 @@
 import uuid
 from collections.abc import Callable
 from dataclasses import dataclass
+from datetime import datetime
 from functools import cached_property
 from pathlib import Path
 from typing import TYPE_CHECKING, Protocol, cast
@@ -51,6 +52,7 @@
 from ..process_host import ProcessHostError, get_process_host
 from ..signals import REBIND_SOURCES, SessionAttribution, SignalWatcher
 from ..tokens import read_usage as tally_usage
+from ..usagereset import UsageReset, parse_reset
 from ..verify import read_frontmatter, status_of
 from .base import (
     CodingCLIAdapter,
@@ -205,7 +207,8 @@ class _QuotaWait:
     clock. An open wait's length is the LONGER of the two elapsed spans, so a
     host suspend (monotonic frozen, wall running) cannot stretch the cap.
     `closed_s` sums the waits that already ended; `evidence` is the pane line
-    that admitted the open one."""
+    that admitted the open one, `resets` its parsed reset (`UsageReset.value`,
+    #610), None when the line named none."""
 
     waiting: bool = False
     started_mono: float = 0.0
@@ -213,6 +216,7 @@ class _QuotaWait:
     frozen_remaining: float = 0.0
     closed_s: float = 0.0
     evidence: str | None = None
+    resets: str | None = None
 
     def open_s(self) -> float:
         if not self.waiting:
@@ -223,6 +227,13 @@ def total_s(self) -> float:
         return self.closed_s + self.open_s()
 
 
+def _local_now() -> datetime:
+    """The aware local "now" a usage-limit reset clause is resolved against
+    (#610). Read off this module's wall clock, so the reset moves with the
+    session's own clock (and a test steering that clock steers this too)."""
+    return datetime.fromtimestamp(time.time()).astimezone()
+
+
 # min spacing between heartbeat.json overwrites in wait_for_completion; the
 # heartbeat's staleness is what makes a frozen orchestrator (#157) diagnosable.
 HEARTBEAT_INTERVAL_S = 30.0
@@ -1498,15 +1509,17 @@ def produced_work() -> bool:
                 handle, stop_seen, activity_seen or transcript_work_seen or usage_seen
             )
 
-        def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
+        def stall_exit(
+            parked_now: str | None, usage_now: str | None, resets_now: str | None = None
+        ) -> SessionResult:
             """The non-completion exit of a stalled session (DW-348, #610):
             resolve, then re-probe liveness. A now-dead window is ``crashed``
             (never parked or usage-limited: nothing waits on a human once the CLI
             is gone). Otherwise ``stalled`` with ``accept_result=False``: an
             artifact on disk cannot upgrade the stall to completed (it may be
             stale or mid-write; only a Stop or window death vouches for it), and
-            ``parked_now`` / ``usage_now`` label it. Both exits carry the
-            rollout."""
+            ``parked_now`` / ``usage_now`` / ``resets_now`` label it. Both exits
+            carry the rollout."""
             try_resolve()
             if self._probe_liveness(handle, "stall") is False:
                 return self._final(
@@ -1532,7 +1545,11 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
             )
             if parked_now is not None:
                 return dataclasses.replace(
-                    stalled, parked=True, parked_evidence=parked_now, usage_limited=usage_now
+                    stalled,
+                    parked=True,
+                    parked_evidence=parked_now,
+                    usage_limited=usage_now,
+                    usage_limit_resets=resets_now if usage_now is not None else None,
                 )
             return stalled
 
@@ -1557,7 +1574,7 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                     )
                     evidence = quota.evidence
                     self._end_quota_wait(handle, quota, "cap")
-                    return stall_exit(evidence, evidence)
+                    return stall_exit(evidence, evidence, quota.resets)
                 # The freeze runs on EVERY tick, not only on heartbeats: a wait
                 # admitted with less than a heartbeat interval left would
                 # otherwise time out between samples. This is the one sanctioned
@@ -1600,9 +1617,11 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                 # is gone, though a remain-on-exit pane still captures), so a
                 # match is confirmed alive first; a probe fault reads "not dead".
                 (usage_hit,) = self._pane_evidence(handle, self._usage_pane_patterns)
-                usage_now = None
+                usage_now = resets_now = None
                 if usage_hit is not None and self._probe_liveness(handle, "timeout") is not False:
                     usage_now = usage_hit[0]
+                    reset = self._usage_reset(handle, usage_hit[1], _local_now())
+                    resets_now = reset.value if reset is not None else None
                 return SessionResult(
                     status="timeout",
                     session_id=session_id,
@@ -1613,6 +1632,7 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                     stop_seen=stop_seen,
                     produced_work=produced_work(),
                     usage_limited=usage_now,
+                    usage_limit_resets=resets_now,
                 )
             # Hard-stop poll (#319), per-iteration and deliberately NOT inside
             # the heartbeat throttle below: the loop's own wait is capped at 5s
@@ -1674,6 +1694,30 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                     if wait_hit is not None and not self._quota_wait_tool_open(
                         handle, transcript_path
                     ):
+                        local_now = _local_now()
+                        reset = self._usage_reset(handle, wait_hit[1], local_now)
+                        resets = reset.value if reset is not None else None
+                        cap_left = spec.quota_wait_max_s - quota.closed_s
+                        if (
+                            reset is not None
+                            and reset.at is not None
+                            and (reset.at - local_now).total_seconds() > cap_left
+                        ):
+                            # Reset-beyond-cap (#610): the CLI will not continue
+                            # before the cap would end the wait anyway, so don't
+                            # freeze the clock for it. Ends exactly as the cap
+                            # does: stalled + parked + usage-limited, never
+                            # completed. An unresolved reset cannot be compared
+                            # and waits as before (the cap still bounds it).
+                            self._note_lifecycle(
+                                handle.task_id,
+                                "quota-wait-skipped",
+                                reason="reset-beyond-cap",
+                                evidence=wait_hit[0],
+                                resets_at=resets,
+                                cap_left_s=round(cap_left, 3),
+                            )
+                            return stall_exit(wait_hit[0], wait_hit[0], resets)
                         frozen = max(
                             min(remaining, wall_deadline - time.time()),
                             QUOTA_WAIT_MIN_REMAINING_S,
@@ -1684,12 +1728,14 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                             round(frozen, 3),
                             round(quota.closed_s, 3),
                             spec.quota_wait_max_s,
+                            resets,
                         )
                         quota.waiting = True
                         quota.started_mono = time.monotonic()
                         quota.started_wall = time.time()
                         quota.frozen_remaining = frozen
                         quota.evidence = wait_hit[0]
+                        quota.resets = resets
                 if not saw_session_start and not session_start_noted:
                     session_start_noted = self._note_session_start_missing(
                         handle, now - loop_started
@@ -1723,6 +1769,13 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                             if quota_enabled
                             else {}
                         ),
+                        # the open wait's parsed reset (#610), while waiting
+                        # on a line that named one.
+                        **(
+                            {"quota_resets_at": quota.resets}
+                            if quota.waiting and quota.resets is not None
+                            else {}
+                        ),
                     },
                 )
                 # Mid-session spec-status transition sampling (#276 M2) rides the
@@ -2004,7 +2057,11 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                     )
                     if parked_now is None and parked_hit is not None:
                         parked_now = parked_hit[0]
-                    usage_now = usage_hit[0] if usage_hit is not None else None
+                    usage_now = resets_now = None
+                    if usage_hit is not None:
+                        usage_now = usage_hit[0]
+                        reset = self._usage_reset(handle, usage_hit[1], _local_now())
+                        resets_now = reset.value if reset is not None else None
                     if parked_now is None:
                         parked_now = usage_now
                     if parked_now is not None:
@@ -2048,7 +2105,7 @@ def stall_exit(parked_now: str | None, usage_now: str | None) -> SessionResult:
                     # persistent failure. A dead window is never labelled parked:
                     # nothing is waiting on a human once the CLI is gone. The
                     # probe fault is crumbed (`site="stall"`, DW-454).
-                    return stall_exit(parked_now, usage_now)
+                    return stall_exit(parked_now, usage_now, resets_now)
                 continue
             # Drop a nested CLI's events before they can re-point the identity
             # or transcript, set stop_seen, spend nudges or re-arm the stall
@@ -2644,7 +2701,10 @@ def _note_quota_wait_started(
         remaining_s: float,
         waited_s: float,
         cap_s: float,
+        resets_at: str | None = None,
     ) -> None:
+        # the parsed reset (#610), present-only on both records
+        resets = {"resets_at": resets_at} if resets_at is not None else {}
         self._note_lifecycle(
             handle.task_id,
             "quota-wait-started",
@@ -2652,6 +2712,7 @@ def _note_quota_wait_started(
             remaining_s=remaining_s,
             waited_s=waited_s,
             cap_s=cap_s,
+            **resets,
         )
         if self.journal is None:
             return
@@ -2662,10 +2723,24 @@ def _note_quota_wait_started(
                 remaining_s=remaining_s,
                 waited_s=waited_s,
                 cap_s=cap_s,
+                **resets,
             )
         except OSError:
             pass
 
+    def _usage_reset(self, handle: SessionHandle, line: str, now: datetime) -> UsageReset | None:
+        """The reset clause of a matched usage-limit pane line (#610), parsed
+        from the FULL line (the evidence excerpt may cut it). A clause that does
+        not resolve is a visible degrade: a `usage-reset-unparsed` crumb
+        (`reason` = `zone-unavailable` | `unparsed`, `raw`), and the caller
+        carries the raw text in place of a time."""
+        reset = parse_reset(line, now)
+        if reset is not None and reset.unresolved is not None:
+            self._note_lifecycle(
+                handle.task_id, "usage-reset-unparsed", reason=reset.unresolved, raw=reset.raw
+            )
+        return reset
+
     def _note_quota_wait_cap(
         self, handle: SessionHandle, evidence: str | None, waited_s: float, cap_s: float
     ) -> None:
diff --git a/src/bmad_loop/engine.py b/src/bmad_loop/engine.py
index a2fbf18d1..7d2a2ba52 100644
--- a/src/bmad_loop/engine.py
+++ b/src/bmad_loop/engine.py
@@ -3080,6 +3080,8 @@ def _run_workflows(self, stage: str, task: StoryTask, seq: int) -> bool:
                     wf_extras["parked_evidence"] = result.parked_evidence
             if result.usage_limited:
                 wf_extras["usage_limited"] = result.usage_limited
+            if result.usage_limit_resets:
+                wf_extras["usage_limit_resets"] = result.usage_limit_resets
             if result.quota_wait_s > 0:
                 wf_extras["quota_wait_s"] = round(result.quota_wait_s, 1)
             self.journal.append(
@@ -8393,6 +8395,10 @@ def _session_end_extras(self, result: SessionResult, usage: TokenUsage | None =
         # verdict from the token veto.
         if result.usage_limited:
             extras["usage_limited"] = result.usage_limited
+        # the limit's reset, parsed from the same line (#610): ISO-8601, or the
+        # raw clause when it did not resolve.
+        if result.usage_limit_resets:
+            extras["usage_limit_resets"] = result.usage_limit_resets
         # usage-limit quota wait (DW-396): present-only — the seconds the session
         # sat behind a usage-window reset with its timeout frozen.
         if result.quota_wait_s > 0:
diff --git a/src/bmad_loop/escalation.py b/src/bmad_loop/escalation.py
index 906c8f752..31f4385ec 100644
--- a/src/bmad_loop/escalation.py
+++ b/src/bmad_loop/escalation.py
@@ -252,10 +252,14 @@ def usage_limit_pause_reason(role: str, result: SessionResult) -> str:
     Reached through ``env_fault_pause_reason`` and ``parked_pause_reason`` when
     ``result.usage_limited`` is set, so no pause site names it directly. Composed
     over `session_failure_reason`, like its siblings, so the #489 lost-session
-    suffix survives. The evidence is the visible-pane match; the tail names the
-    operator's ways out, since no retry gets past the limit on its own."""
+    suffix survives. The evidence is the visible-pane match, followed by
+    ``; resets <value>`` when the line named a reset (``usage_limit_resets``:
+    ISO-8601, or the raw clause when it did not resolve; read as given, no
+    clock here); the tail names the operator's ways out, since no retry gets
+    past the limit on its own."""
+    resets = f"; resets {result.usage_limit_resets}" if result.usage_limit_resets else ""
     return (
-        f"usage limit: {session_failure_reason(role, result)} ({result.usage_limited}; "
+        f"usage limit: {session_failure_reason(role, result)} ({result.usage_limited}{resets}; "
         "the coding CLI is blocked by a usage limit — add credits, switch model or "
         "wait for the reset, then bmad-loop resolve <run>)"
     )
diff --git a/src/bmad_loop/tui/data.py b/src/bmad_loop/tui/data.py
index 7869804d5..d7298d271 100644
--- a/src/bmad_loop/tui/data.py
+++ b/src/bmad_loop/tui/data.py
@@ -806,6 +806,40 @@ def _idle_tool(journal_entries: list[dict[str, Any]], start: int, task_id: str)
     return tool
 
 
+def _quota_wait(
+    journal_entries: list[dict[str, Any]], start: int, task_id: str
+) -> tuple[float | None, str | None]:
+    """The open session's usage-limit quota wait (DW-396, #610): ``(since,
+    resets_at)`` from the last `quota-wait-started` for `task_id` after index
+    `start` — its journal `ts` and its string `resets_at` (None when the wait
+    line named no reset) — or ``(None, None)`` when no wait is open: a later
+    `quota-wait-ended` for the same task closes it, and a wait can re-open
+    after one ends, so the latest wins. A `quota-wait-started` without a finite
+    numeric `ts` is skipped without erasing an earlier open wait, as
+    `_idle_since` skips a malformed stamp. Never raises on a malformed entry."""
+    since: float | None = None
+    resets: str | None = None
+    for entry in journal_entries[start + 1 :]:
+        if str(entry.get("task_id")) != task_id:
+            continue
+        kind = entry.get("kind")
+        if kind == "quota-wait-started":
+            raw = entry.get("ts")
+            if isinstance(raw, (int, float)) and not isinstance(raw, bool):
+                try:
+                    stamp = float(raw)
+                except OverflowError:
+                    continue
+                if math.isfinite(stamp):
+                    since = stamp
+                    raw_resets = entry.get("resets_at")
+                    resets = raw_resets if isinstance(raw_resets, str) and raw_resets else None
+        elif kind == "quota-wait-ended":
+            since = None
+            resets = None
+    return since, resets
+
+
 def active_task_id(run_dir: Path, journal_entries: list[dict[str, Any]]) -> str | None:
     """Task whose agent session is currently open: the last session-start
     without a later session-end. Falls back to the newest file in logs/ —
@@ -863,6 +897,17 @@ class ActiveAgent:
     # appends `· in <tool>` from it unless it is `none`. APPENDED, like
     # `idle_since`.
     idle_tool: str | None = None
+    # Wall timestamp the session's open usage-limit quota wait began (DW-396) —
+    # the journal `ts` of the last `quota-wait-started` not closed by a later
+    # `quota-wait-ended` — or None when no wait is open. The header renders
+    # `· quota wait <age>` from it IN PLACE OF the idle notice: the transcript
+    # sits still by design while the CLI waits out a usage-window reset, so the
+    # session is neither idle nor stuck. APPENDED, like `idle_since`.
+    quota_wait_since: float | None = None
+    # That open wait's parsed reset (#610): ISO-8601, or the raw clause text
+    # when it did not resolve; None when the wait line named none. The header
+    # appends `· resets <time>` from it. APPENDED.
+    quota_resets_at: str | None = None
 
 
 def _story_key_from_task_id(task_id: str, role: str) -> str:
@@ -918,6 +963,7 @@ def active_agent(
             name, model = resolved.name, resolved.model
         story_raw = entry.get("story_key")
         story_key = str(story_raw) if story_raw else _story_key_from_task_id(task_id, role)
+        quota_since, quota_resets = _quota_wait(journal_entries, start_index, task_id)
         return ActiveAgent(
             task_id=task_id,
             story_key=story_key,
@@ -926,6 +972,8 @@ def active_agent(
             model=model,
             idle_since=_idle_since(journal_entries, start_index, task_id),
             idle_tool=_idle_tool(journal_entries, start_index, task_id),
+            quota_wait_since=quota_since,
+            quota_resets_at=quota_resets,
         )
     except _MALFORMED_AGENT_FAULTS as e:
         return UnreadableAgent(error=f"malformed session-start or snapshot: {_describe(e)}")
diff --git a/src/bmad_loop/tui/widgets.py b/src/bmad_loop/tui/widgets.py
index cd0d7ead6..782756984 100644
--- a/src/bmad_loop/tui/widgets.py
+++ b/src/bmad_loop/tui/widgets.py
@@ -9,6 +9,7 @@
 
 import json
 import time
+from datetime import datetime
 from pathlib import Path
 from typing import Any, Callable
 
@@ -147,6 +148,20 @@ def _format_age(seconds: float) -> str:
     return f"{minutes // 60}h{minutes % 60:02d}m"
 
 
+def _format_reset(value: str) -> str:
+    """A quota wait's reset for the header's `· resets <time>` text (#610): an
+    aware ISO-8601 value as this host's local weekday and time (`Mon 12:50`),
+    so the operator reads it in the clock they see; anything else — the raw
+    clause of a reset that did not resolve — as given."""
+    try:
+        at = datetime.fromisoformat(value)
+    except ValueError:
+        return value
+    if at.tzinfo is None:
+        return value
+    return at.astimezone().strftime("%a %H:%M")
+
+
 class RunHeader(Static):
     """One-glance summary of the selected run, or the empty-state hint."""
 
@@ -246,7 +261,19 @@ def show_run(
                 text.append(f" · {agent.model}", style="cyan")
             if agent.role:
                 text.append(f" · {agent.role}", style="dim")
-            if agent.idle_since is not None:
+            if agent.quota_wait_since is not None:
+                # A usage-limit quota wait is open (DW-396): the CLI is waiting
+                # out a usage-window reset it continues from by itself, with the
+                # session timeout frozen. Its transcript sits still by design, so
+                # this replaces the idle notice — the session is neither idle
+                # nor stuck. `· resets <time>` names the parsed reset (#610).
+                text.append(
+                    f" · quota wait {_format_age(time.time() - agent.quota_wait_since)}",
+                    style="yellow",
+                )
+                if agent.quota_resets_at:
+                    text.append(f" · resets {_format_reset(agent.quota_resets_at)}", style="yellow")
+            elif agent.idle_since is not None:
                 # The transcript has sat still past the stall grace (#680): the
                 # pane may still be repainting a spinner, so this is the one
                 # surface that separates a session working from one parked in a
diff --git a/src/bmad_loop/usagereset.py b/src/bmad_loop/usagereset.py
new file mode 100644
index 000000000..925a75081
--- /dev/null
+++ b/src/bmad_loop/usagereset.py
@@ -0,0 +1,141 @@
+"""Parse the ``resets …`` clause of a coding CLI's usage-limit line (#610).
+
+Pure: no clock reads, no I/O beyond the stdlib zone database. The caller
+passes ``now`` (an aware local datetime) and the full pane line that a
+``usage_limit_patterns`` / ``usage_wait_patterns`` entry matched; the result
+feeds the pause reason, ``heartbeat.json`` (``quota_resets_at``), the
+``session-end`` journal field ``usage_limit_resets`` and the quota wait's
+reset-beyond-cap rule.
+
+Grammar, after the literal ``resets ``::
+
+    [<Weekday> | <Mon> <D> at ]H[:MM](am|pm)[ (<Area/City>)]
+
+with weekdays ``Mon``..``Sun`` and months ``Jan``..``Dec``, which covers the
+forms seen in the field: ``7:20pm``, ``12:50pm (Asia/Ho_Chi_Minh)``,
+``6pm (Europe/Warsaw)``, ``Mon 12:00am``, ``Sep 15 at 7pm``. The reset is the
+next occurrence of that wall time strictly after ``now``: in the named zone
+when the clause names one, else in ``now``'s own zone.
+
+Degrade contract: :func:`parse_reset` never raises. A line with no clause is
+``None``. A clause it cannot resolve keeps its raw text with ``at=None`` and
+names why in ``unresolved``: ``"zone-unavailable"`` when the named zone is not
+in this host's zone database (Windows without the ``tzdata`` package, say), and
+``"unparsed"`` for any other shape. The caller makes that degrade visible (the
+generic adapter writes a ``usage-reset-unparsed`` crumb and carries the raw
+text); it is never read as "no reset".
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import date, datetime
+from datetime import time as dtime
+from datetime import timedelta, tzinfo
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+__all__ = ["UsageReset", "parse_reset"]
+
+_WEEKDAYS = ("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")
+_MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
+
+# The clause: `resets ` followed by at least one non-space character. Anything
+# shorter is no clause at all.
+_CLAUSE_RE = re.compile(r"\bresets (?P<rest>\S.*)")
+_TIME_RE = re.compile(
+    r"(?:(?P<wd>" + "|".join(_WEEKDAYS) + r") "
+    r"|(?P<mon>" + "|".join(_MONTHS) + r") (?P<day>\d{1,2}) at )?"
+    r"(?P<hour>\d{1,2})(?::(?P<minute>\d{2}))?(?P<ampm>am|pm)(?![A-Za-z0-9])"
+    r"(?: \((?P<zone>[A-Za-z][A-Za-z0-9_+-]*(?:/[A-Za-z0-9_+-]+)+)\))?"
+)
+# The longest raw text kept for a clause that did not parse.
+_RAW_MAX = 80
+# How many years ahead a `<Mon> <D>` clause may land (Feb 29 needs up to 4).
+_YEARS_AHEAD = 5
+
+
+@dataclass(frozen=True)
+class UsageReset:
+    """One parsed reset clause. ``raw`` is the clause text after ``resets``
+    (the matched span when it parsed, else the line's remainder, truncated).
+    ``at`` is the resolved reset, aware, in the named zone or ``now``'s; None
+    when unresolved, and then ``unresolved`` names why."""
+
+    raw: str
+    at: datetime | None
+    unresolved: str | None
+
+    @property
+    def value(self) -> str:
+        """What the surfaces carry: ISO-8601 when resolved, else the raw text."""
+        return self.at.isoformat() if self.at is not None else self.raw
+
+
+def parse_reset(line: str, now: datetime) -> UsageReset | None:
+    """The reset clause in ``line``, resolved against ``now``; None when the
+    line has no ``resets `` clause. Never raises (module docstring)."""
+    clause = _CLAUSE_RE.search(line)
+    if clause is None:
+        return None
+    rest = clause.group("rest").rstrip()
+    m = _TIME_RE.match(rest)
+    if m is None or (m.group("zone") is None and rest[m.end() :].startswith(" (")):
+        # No time, or a parenthesised zone of a shape the grammar does not
+        # know: resolving it in the local zone would be silently wrong.
+        return _unresolved(rest[:_RAW_MAX], "unparsed")
+    raw = m.group(0)
+    hour = int(m.group("hour"))
+    minute = int(m.group("minute") or 0)
+    if not 1 <= hour <= 12 or minute > 59:
+        return _unresolved(raw, "unparsed")
+    hour = hour % 12 + (12 if m.group("ampm") == "pm" else 0)
+    zone_name = m.group("zone")
+    tz: tzinfo | None = now.tzinfo
+    if zone_name is not None:
+        try:
+            tz = ZoneInfo(zone_name)
+        except (ZoneInfoNotFoundError, ValueError, OSError):
+            return _unresolved(raw, "zone-unavailable")
+    try:
+        local_now = now.astimezone(tz) if tz is not None else now
+        at = _next_occurrence(m, dtime(hour, minute), local_now, tz)
+    except (ValueError, OverflowError):
+        return _unresolved(raw, "unparsed")
+    if at is None:
+        return _unresolved(raw, "unparsed")
+    return UsageReset(raw=raw, at=at, unresolved=None)
+
+
+def _unresolved(raw: str, why: str) -> UsageReset:
+    return UsageReset(raw=raw, at=None, unresolved=why)
+
+
+def _next_occurrence(
+    m: re.Match[str], wall: dtime, now: datetime, tz: tzinfo | None
+) -> datetime | None:
+    """The first ``wall`` time strictly after ``now`` on a date the clause
+    allows. Dates are built with ``datetime.combine`` in ``tz``, so a DST
+    change between now and the reset keeps the stated wall time."""
+
+    def at(day: date) -> datetime:
+        return datetime.combine(day, wall, tzinfo=tz)
+
+    today = now.date()
+    if m.group("mon") is not None:
+        month = _MONTHS.index(m.group("mon")) + 1
+        day = int(m.group("day"))
+        for year in range(today.year, today.year + _YEARS_AHEAD):
+            try:
+                candidate = at(date(year, month, day))
+            except ValueError:
+                continue
+            if candidate > now:
+                return candidate
+        return None
+    if m.group("wd") is not None:
+        ahead = (_WEEKDAYS.index(m.group("wd")) - today.weekday()) % 7
+        candidate = at(today + timedelta(days=ahead))
+        return candidate if candidate > now else at(today + timedelta(days=ahead + 7))
+    candidate = at(today)
+    return candidate if candidate > now else at(today + timedelta(days=1))
diff --git a/tests/test_engine.py b/tests/test_engine.py
index ffbdcb49a..bd09a8a30 100644
--- a/tests/test_engine.py
+++ b/tests/test_engine.py
@@ -15401,6 +15401,36 @@ def test_session_end_carries_quota_wait_s_only_when_positive(project):
     assert "quota_wait_s" not in plain_end
 
 
+def test_session_end_carries_usage_limit_resets_only_when_set(project):
+    """#610: the usage limit's parsed reset rides `session-end` present-only and
+    names itself in the pause reason.
+    ABLATION: drop the `usage_limit_resets` extras line from `_session_end_extras`
+    and the session-end assertion fails."""
+    write_sprint(project, {"1-1-a": "ready-for-dev"})
+    evidence = "pane matched 'usage-pattern': session limi" + "t · resets 7:20pm"
+    engine, _ = make_engine(
+        project,
+        [
+            SessionResult(
+                status="stalled",
+                parked=True,
+                parked_evidence=evidence,
+                usage_limited=evidence,
+                usage_limit_resets="2026-10-25T19:20:00+00:00",
+            )
+        ],
+    )
+    engine.run()
+    end = [e for e in engine.journal.entries() if e["kind"] == "session-end"][-1]
+    assert end["usage_limit_resets"] == "2026-10-25T19:20:00+00:00"
+    assert engine.state.paused_reason is not None
+    assert "; resets 2026-10-25T19:20:00+00:00" in engine.state.paused_reason
+    engine2, _ = make_engine(project, [SessionResult(status="stalled")])
+    engine2.run()
+    plain_end = [e for e in engine2.journal.entries() if e["kind"] == "session-end"][-1]
+    assert "usage_limit_resets" not in plain_end
+
+
 def test_session_env_fault_pauses_dev_without_burning_budget(project):
     """A dev session classified an environment fault (#194) pauses the run at the
     first story rather than charging the attempt; the decision + session-end carry
diff --git a/tests/test_escalation.py b/tests/test_escalation.py
index f0db06adb..6a818060c 100644
--- a/tests/test_escalation.py
+++ b/tests/test_escalation.py
@@ -388,6 +388,23 @@ def test_review_usage_limited_pauses_with_usage_reason(status):
         assert _USAGE_EVIDENCE in decision.reason
 
 
+@pytest.mark.parametrize(
+    "resets", ["2026-10-25T19:20:00+07:00", "7:20pm (Mars/Olympus_Mons)"], ids=["iso", "raw"]
+)
+def test_usage_reason_names_the_reset(resets):
+    """#610: a parsed reset rides the reason as `; resets <value>` right after
+    the evidence — ISO-8601, or the raw clause when it did not resolve, read as
+    given (no clock here). Without one the reason is unchanged.
+    ABLATION: drop the `resets` suffix from `usage_limit_pause_reason` and the
+    first assertion fails."""
+    for result in _usage_limited_results("stalled"):
+        with_reset = dataclasses.replace(result, usage_limit_resets=resets)
+        reason = decide_dev(_task(attempt=1), with_reset, None, POLICY).reason
+        assert f"{_USAGE_EVIDENCE}; resets {resets}; the coding CLI" in reason
+        plain = decide_dev(_task(attempt=1), result, None, POLICY).reason
+        assert "resets" not in plain.replace(_USAGE_EVIDENCE, "")
+
+
 def test_usage_limit_reason_keeps_the_lost_session_suffix():
     """Composed over `session_failure_reason` (#489), like its siblings."""
     vanished = SessionResult(status="stalled", usage_limited="x", session_vanished=True)
diff --git a/tests/test_generic_tmux.py b/tests/test_generic_tmux.py
index cce3126df..1e72d7369 100644
--- a/tests/test_generic_tmux.py
+++ b/tests/test_generic_tmux.py
@@ -19,6 +19,7 @@
 import threading
 import time
 import uuid
+from datetime import datetime, timezone
 from pathlib import Path
 
 import pytest
@@ -12723,10 +12724,18 @@ def finish_spec(self) -> None:
         )
 
 
-def _quota_adapter(tmp_path, monkeypatch, *, screen=QUOTA_SCREEN, grace=600.0):
+# The local "now" the wait line's `resets 7:20pm` resolves against in these
+# tests (#610): one minute before the reset, inside every cap below, so the
+# reset-beyond-cap rule never skips a wait a test means to open.
+QUOTA_NOW = datetime(2026, 10, 25, 19, 19, tzinfo=timezone.utc)
+QUOTA_RESETS = "2026-10-25T19:20:00+00:00"
+
+
+def _quota_adapter(tmp_path, monkeypatch, *, screen=QUOTA_SCREEN, grace=600.0, now=QUOTA_NOW):
     """A claude dev adapter over a `_UnitMux` showing `screen`, a fake journal,
-    a pane log, a transcript, captured heartbeats and independently steerable
-    monotonic/wall clocks."""
+    a pane log, a transcript, captured heartbeats, independently steerable
+    monotonic/wall clocks and a pinned local `now` for the reset parse."""
+    monkeypatch.setattr(generic, "_local_now", lambda: now)
     monkeypatch.setattr(generic, "RESULT_GRACE_S", 0.0)
     monkeypatch.setattr(generic, "RESULT_POLL_S", 0.0)
     mux = _UnitMux(screen=screen)
@@ -12833,6 +12842,7 @@ def script(call_n):
         "remaining_s": 210.0,
         "waited_s": 0.0,
         "cap_s": 3600.0,
+        "resets_at": QUOTA_RESETS,
     }
     assert ended == {
         "kind": "quota-wait-ended",
@@ -13133,6 +13143,139 @@ def script(call_n):
     assert result.quota_wait_s == 120.0
 
 
+# ------------------------------------------ usage-limit reset parse (#610)
+#
+# The matched wait/limit line's `resets …` clause is parsed (`usagereset`) from
+# the FULL pane line into `SessionResult.usage_limit_resets`, the heartbeat's
+# `quota_resets_at` and `quota-wait-started`'s `resets_at`. A reset the cap could
+# not outlast skips the wait. `_quota_adapter` pins the local `now`.
+
+
+def test_reset_beyond_cap_skips_the_wait(tmp_path, monkeypatch):
+    """At 12:00 a `resets 7:20pm` line lies 7h20m out, beyond the 1 h cap: the
+    wait the cap would end anyway is never opened. The session ends at the
+    admission heartbeat (mono 1090) stalled + parked with the usage evidence and
+    the parsed reset, never completed, the timeout untouched, no wait recorded.
+
+    Ablation: drop the reset-beyond-cap branch and the wait opens (quota kinds
+    recorded, no `quota-wait-skipped`), running on to its cap."""
+    q = _quota_adapter(
+        tmp_path, monkeypatch, now=datetime(2026, 10, 25, 12, 0, tzinfo=timezone.utc)
+    )
+    result = _drive_quota(q, _quota_spec(tmp_path, cap_s=3600.0))
+    assert (result.status, result.parked) == ("stalled", True)
+    assert result.parked_evidence == result.usage_limited == q.wait_evidence()
+    assert result.usage_limit_resets == QUOTA_RESETS
+    assert result.result_json is None
+    assert result.quota_wait_s == 0.0
+    assert q.quota_kinds() == []
+    assert _lifecycle_events(q.adapter, "quota-wait-started") == []
+    assert _lifecycle_events(q.adapter, "timeout-fired") == []
+    (skipped,) = _lifecycle_events(q.adapter, "quota-wait-skipped")
+    assert skipped["reason"] == "reset-beyond-cap"
+    assert skipped["evidence"] == q.wait_evidence()
+    assert skipped["resets_at"] == QUOTA_RESETS
+    assert skipped["cap_left_s"] == 3600.0
+    assert q.clock["mono"] == 1090.0
+
+
+def test_reset_within_cap_waits(tmp_path, monkeypatch):
+    """At 18:30 the same reset is 50 min out, inside the 1 h cap: the wait opens
+    as before, `quota-wait-started` and the heartbeat carry the parsed reset
+    while waiting (and only then), and the session completes on its Stop after
+    the CLI continues.
+
+    Ablation: compare the reset against the cap with the sign flipped (or
+    against zero) and this skips the wait instead."""
+    q = _quota_adapter(
+        tmp_path, monkeypatch, now=datetime(2026, 10, 25, 18, 30, tzinfo=timezone.utc)
+    )
+
+    def script(call_n):
+        if call_n == 8:
+            _grow(q.transcript, _assistant_line())
+        if call_n == 9:
+            q.finish_spec()
+
+    result = _drive_quota(
+        q,
+        _quota_spec(tmp_path, cap_s=3600.0),
+        events={9: _stop_event("3-1-dev-1", "sess", str(q.transcript))},
+        script=script,
+    )
+    assert result.status == "completed"
+    assert result.usage_limit_resets is None  # it continued: no usage verdict
+    assert _lifecycle_events(q.adapter, "quota-wait-skipped") == []
+    assert q.quota_kinds() == ["quota-wait-started", "quota-wait-ended"]
+    started = next(e for e in q.adapter.journal.entries if e["kind"] == "quota-wait-started")
+    assert started["resets_at"] == QUOTA_RESETS
+    (crumb,) = _lifecycle_events(q.adapter, "quota-wait-started")
+    assert crumb["resets_at"] == QUOTA_RESETS
+    resets = [hb.get("quota_resets_at") for hb in q.heartbeats]
+    # heartbeats at mono 1000/1030/1060 (before), 1090…1180 (waiting), 1210
+    # (the transcript moved: ended ahead of the write)
+    assert resets[:3] == [None] * 3
+    assert resets[3:7] == [QUOTA_RESETS] * 4
+    assert resets[7:] == [None]
+
+
+def test_usage_limited_result_carries_the_parsed_reset(tmp_path, monkeypatch):
+    """Every usage-limited exit carries the reset parsed from the matched line:
+    the stall-expiry gate (quota wait off, silent pane), the timeout-fired look,
+    and the quota-wait cap."""
+    for sub in ("stall", "timeout", "cap"):
+        (tmp_path / sub).mkdir()
+    stall = _quota_adapter(tmp_path / "stall", monkeypatch, grace=120.0)
+    result = _drive_quota(stall, _quota_spec(tmp_path, cap_s=0.0), repaint=False)
+    assert (result.status, result.parked) == ("stalled", True)
+    assert result.usage_limited == stall.wait_evidence()
+    assert result.usage_limit_resets == QUOTA_RESETS
+
+    timeout = _quota_adapter(tmp_path / "timeout", monkeypatch)
+    result = _drive_quota(timeout, _quota_spec(tmp_path, cap_s=0.0))
+    assert result.status == "timeout"
+    assert result.usage_limited == timeout.wait_evidence()
+    assert result.usage_limit_resets == QUOTA_RESETS
+
+    cap = _quota_adapter(tmp_path / "cap", monkeypatch)
+    result = _drive_quota(cap, _quota_spec(tmp_path, cap_s=600.0))
+    assert (result.status, result.parked) == ("stalled", True)
+    assert _lifecycle_events(cap.adapter, "quota-wait-cap")
+    assert result.usage_limit_resets == QUOTA_RESETS
+    for q in (stall, timeout, cap):
+        assert _lifecycle_events(q.adapter, "usage-reset-unparsed") == []
+
+
+@pytest.mark.parametrize(
+    ("clause", "reason"),
+    [("7:20pm (Mars/Olympus_Mons)", "zone-unavailable"), ("in a little while", "unparsed")],
+)
+def test_unparsed_reset_is_crumbed_and_kept_raw(tmp_path, monkeypatch, clause, reason):
+    """A reset that does not resolve (a zone this host's database lacks, an
+    unknown shape) is a visible degrade: a `usage-reset-unparsed` crumb naming
+    why, and the raw clause carried in place of a time. It cannot be compared
+    with the cap, so the wait still opens (the cap bounds it) and ends there
+    with the raw text on the result. The zone lookup is faked, so no host
+    tzdata is read."""
+    from bmad_loop import usagereset
+
+    def no_zone(name):
+        raise usagereset.ZoneInfoNotFoundError(name)
+
+    monkeypatch.setattr(usagereset, "ZoneInfo", no_zone)
+    line = USAGE_SESSION_LINE.replace("7:20pm", clause)
+    q = _quota_adapter(tmp_path, monkeypatch, screen=f"{line}\r\n❯ \r\n")
+    result = _drive_quota(q, _quota_spec(tmp_path, cap_s=600.0))
+    assert (result.status, result.parked) == ("stalled", True)
+    assert result.usage_limit_resets == clause
+    crumbs = _lifecycle_events(q.adapter, "usage-reset-unparsed")
+    assert crumbs and all(c["reason"] == reason and c["raw"] == clause for c in crumbs)
+    assert _lifecycle_events(q.adapter, "quota-wait-skipped") == []
+    started = next(e for e in q.adapter.journal.entries if e["kind"] == "quota-wait-started")
+    assert started["resets_at"] == clause
+    assert any(hb.get("quota_resets_at") == clause for hb in q.heartbeats)
+
+
 # ------------------------------- session-start-missing notice
 #
 # Observation only. A session whose profile maps SessionStart but that has run
diff --git a/tests/test_portability_guard.py b/tests/test_portability_guard.py
index cfe9f208e..eda4bb633 100644
--- a/tests/test_portability_guard.py
+++ b/tests/test_portability_guard.py
@@ -950,6 +950,9 @@
         # exists to draw. Names no path, identifier or prose.
         "regen_cause",
         "remaining",
+        # `quota-wait-started` (#610): the wait line's parsed reset — ISO-8601,
+        # or the raw clause text after `resets` when it did not resolve.
+        "resets_at",
         # `quota-wait-started` (DW-396): the session-timeout seconds the wait
         # froze — a measured float.
         "remaining_s",
@@ -1027,6 +1030,9 @@
         # `session-end` / `workflow-end` (DW-396): the seconds the session sat in a
         # usage-limit quota wait with its timeout frozen — a measured float.
         "quota_wait_s",
+        # `session-end` / `workflow-end` (#610): the usage limit's reset parsed
+        # from the same pane line — ISO-8601, or the raw clause text.
+        "usage_limit_resets",
         "verification_sequence",
         "verification_stage",
         "via",
@@ -1206,6 +1212,7 @@
             "parked_evidence",
             "usage_limited",
             "quota_wait_s",
+            "usage_limit_resets",
         }
     ),
     # The plugin bus's `_log` forwards its OWN `**fields` parameter, so the keys
diff --git a/tests/test_tui_app.py b/tests/test_tui_app.py
index 841b0af20..c6b9efdb4 100644
--- a/tests/test_tui_app.py
+++ b/tests/test_tui_app.py
@@ -16,6 +16,7 @@
 import threading
 import time
 import tomllib
+from datetime import datetime, timezone
 from pathlib import Path
 
 import pytest
@@ -7968,6 +7969,56 @@ async def test_header_agent_line_names_the_waited_tool(project_tree, monkeypatch
         assert "· in" not in str(header.content)
 
 
+async def test_header_open_quota_wait_renders_as_quota_wait_not_idle(project_tree, monkeypatch):
+    """DW-396/#610: an open quota wait renders `· quota wait <age>` IN PLACE OF
+    the idle notice the same silent transcript would otherwise raise, followed
+    by `· resets <local weekday time>` for a resolved reset or the raw clause as
+    given; once the wait closes, the idle notice is back.
+
+    ABLATION: drop the `quota_wait_since` branch in `show_run` and the first
+    assertion reddens (the line reads `· idle`)."""
+    monkeypatch.setattr(widgets.time, "time", lambda: 10_000.0)
+    state = RunState(
+        run_id="r1",
+        project=str(project_tree.project),
+        started_at="now",
+        tasks={"1-1-alpha": StoryTask(story_key="1-1-alpha", epic=1, phase=Phase.DEV_RUNNING)},
+    )
+    idle = data.ActiveAgent(
+        task_id="1-1-alpha-dev-1",
+        story_key="1-1-alpha",
+        role="dev",
+        name="claude",
+        model="opus",
+        idle_since=10_000.0 - 20 * 60,
+        idle_tool="none",
+    )
+    waiting = dataclasses.replace(idle, quota_wait_since=10_000.0 - 17 * 60)
+    # A resolved reset renders in this host's local clock, whatever its zone.
+    local = datetime(2026, 10, 26, 12, 50).astimezone()
+    app = BmadLoopApp(project_tree.project)
+    async with app.run_test():
+        header = dashboard(app).query_one("#runheader", RunHeader)
+        header.show_run("r1", data.RUNNING, state, agent=waiting)
+        assert "claude · opus · dev · quota wait 17m" in str(header.content)
+        assert "idle" not in str(header.content)
+        assert "resets" not in str(header.content)
+
+        resolved = dataclasses.replace(
+            waiting, quota_resets_at=local.astimezone(timezone.utc).isoformat()
+        )
+        header.show_run("r1", data.RUNNING, state, agent=resolved)
+        assert "· quota wait 17m · resets Mon 12:50" in str(header.content)
+
+        raw = dataclasses.replace(waiting, quota_resets_at="7pm (Mars/Olympus_Mons)")
+        header.show_run("r1", data.RUNNING, state, agent=raw)
+        assert "· quota wait 17m · resets 7pm (Mars/Olympus_Mons)" in str(header.content)
+
+        header.show_run("r1", data.RUNNING, state, agent=idle)  # quota-wait-ended
+        assert "· idle 20m" in str(header.content)
+        assert "quota wait" not in str(header.content)
+
+
 async def test_header_marks_stale_state_unreadable_agent_and_read_faults(project_tree):
     """DW-472/474/475 at the header: a stale last-good state gets its own warning
     line, a state never parsed names why, an unreadable agent says so instead of
diff --git a/tests/test_tui_data.py b/tests/test_tui_data.py
index a7b2df9dd..7c0256de9 100644
--- a/tests/test_tui_data.py
+++ b/tests/test_tui_data.py
@@ -1043,6 +1043,63 @@ def test_active_agent_idle_since_ignores_other_tasks_and_earlier_sessions():
     assert agent is not None and agent.idle_since is None
 
 
+def test_open_quota_wait_renders_as_quota_wait_not_idle():
+    """DW-396/#610: the last `quota-wait-started` for the open session's task,
+    not closed by a later `quota-wait-ended`, sets `quota_wait_since` to its
+    journal `ts` and `quota_resets_at` to its `resets_at` — alongside the open
+    idle stretch the wait necessarily has, which the header then renders as a
+    quota wait instead. A wait can re-open after it ends: the latest wins.
+
+    ABLATION: drop the `_quota_wait` derivation from `active_agent` and the
+    first assertion reddens."""
+    task = "1-1-alpha-dev-3"
+    idle = {"kind": "session-idle", "task_id": task, "since_ts": 5030.0}
+    started = {
+        "kind": "quota-wait-started",
+        "task_id": task,
+        "ts": 5090.0,
+        "resets_at": "2026-10-25T19:20:00+00:00",
+    }
+    ended = {"kind": "quota-wait-ended", "task_id": task, "ts": 5600.0, "how": "transcript-active"}
+    agent = data.active_agent([_stamped_start(), idle, started], None)
+    assert isinstance(agent, data.ActiveAgent)
+    assert (agent.quota_wait_since, agent.quota_resets_at) == (5090.0, "2026-10-25T19:20:00+00:00")
+    assert agent.idle_since == 5030.0  # still idle: the header chooses the wait
+
+    agent = data.active_agent([_stamped_start(), idle, started, ended], None)
+    assert isinstance(agent, data.ActiveAgent)
+    assert (agent.quota_wait_since, agent.quota_resets_at) == (None, None)
+
+    reopened = {"kind": "quota-wait-started", "task_id": task, "ts": 6000.0}
+    agent = data.active_agent([_stamped_start(), started, ended, reopened], None)
+    assert isinstance(agent, data.ActiveAgent)
+    assert (agent.quota_wait_since, agent.quota_resets_at) == (6000.0, None)
+
+    # another task's wait, an earlier session's, and a session-end all read as none
+    other = dict(started, task_id="2-2-beta-dev-1")
+    for entries in (
+        [_stamped_start(), other],
+        [started, _stamped_start()],
+        [_stamped_start(), started, {"kind": "session-end", "task_id": task}],
+    ):
+        agent = data.active_agent(entries, None)
+        assert not isinstance(agent, data.ActiveAgent) or agent.quota_wait_since is None
+
+
+def test_open_quota_wait_never_raises_on_malformed_entry():
+    """A `quota-wait-started` without a finite numeric `ts` is skipped without
+    erasing an earlier open wait; a non-string `resets_at` reads as none."""
+    task = "1-1-alpha-dev-3"
+    good = {"kind": "quota-wait-started", "task_id": task, "ts": 5090.0, "resets_at": 7}
+    for ts in (None, "soon", True, float("nan"), float("inf"), 10**1000):
+        bad = {"kind": "quota-wait-started", "task_id": task, "ts": ts, "resets_at": "x"}
+        agent = data.active_agent([_stamped_start(), bad], None)
+        assert isinstance(agent, data.ActiveAgent) and agent.quota_wait_since is None
+        agent = data.active_agent([_stamped_start(), good, bad], None)
+        assert isinstance(agent, data.ActiveAgent)
+        assert (agent.quota_wait_since, agent.quota_resets_at) == (5090.0, None)
+
+
 def test_active_agent_idle_since_never_raises_on_malformed_entry():
     """A `session-idle` without a numeric `since_ts` is skipped (the TUI ages the
     text from it); the agent itself is still derived."""
diff --git a/tests/test_usagereset.py b/tests/test_usagereset.py
new file mode 100644
index 000000000..08078a238
--- /dev/null
+++ b/tests/test_usagereset.py
@@ -0,0 +1,205 @@
+"""Tests for usagereset.py: the usage-limit `resets …` clause parse (#610).
+
+None of these depend on the host's zone database: the named-zone route is
+pinned by monkeypatching the module's `ZoneInfo` lookup to a fixed offset, and
+the one real-zone test skips when the zone is absent."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone, tzinfo
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import pytest
+
+from bmad_loop import usagereset
+from bmad_loop.usagereset import UsageReset, parse_reset
+
+UTC = timezone.utc
+PLUS7 = timezone(timedelta(hours=7), "+07")
+PLUS2 = timezone(timedelta(hours=2), "+02")
+# Sunday 2026-10-25 15:00 UTC.
+NOW = datetime(2026, 10, 25, 15, 0, tzinfo=UTC)
+
+
+@pytest.fixture
+def fixed_zones(monkeypatch: pytest.MonkeyPatch) -> dict[str, tzinfo]:
+    """The module's zone lookup, answered from a fixed table (no tzdata)."""
+    zones: dict[str, tzinfo] = {"Asia/Ho_Chi_Minh": PLUS7, "Europe/Warsaw": PLUS2}
+
+    def lookup(name: str) -> tzinfo:
+        try:
+            return zones[name]
+        except KeyError:
+            raise ZoneInfoNotFoundError(name) from None
+
+    monkeypatch.setattr(usagereset, "ZoneInfo", lookup)
+    return zones
+
+
+def _at(line: str, now: datetime = NOW) -> datetime:
+    reset = parse_reset(line, now)
+    assert reset is not None and reset.unresolved is None, reset
+    assert reset.at is not None
+    return reset.at
+
+
+# --- every field form --------------------------------------------------------
+
+
+def test_time_with_minutes_resolves_in_nows_zone() -> None:
+    reset = parse_reset("limit · resets 7:20pm", NOW)
+    assert reset == UsageReset(
+        raw="7:20pm", at=datetime(2026, 10, 25, 19, 20, tzinfo=UTC), unresolved=None
+    )
+    assert reset.value == "2026-10-25T19:20:00+00:00"
+
+
+def test_time_with_named_zone(fixed_zones: dict[str, tzinfo]) -> None:
+    reset = parse_reset("limit · resets 12:50pm (Asia/Ho_Chi_Minh)", NOW)
+    assert reset is not None
+    assert reset.raw == "12:50pm (Asia/Ho_Chi_Minh)"
+    # 15:00 UTC is 22:00 in +07: 12:50pm there is tomorrow.
+    assert reset.at == datetime(2026, 10, 26, 12, 50, tzinfo=PLUS7)
+    assert reset.value == "2026-10-26T12:50:00+07:00"
+
+
+def test_hour_only_with_named_zone(fixed_zones: dict[str, tzinfo]) -> None:
+    # 15:00 UTC is 17:00 in +02: 6pm there is today.
+    assert _at("resets 6pm (Europe/Warsaw)") == datetime(2026, 10, 25, 18, 0, tzinfo=PLUS2)
+
+
+def test_weekday_form() -> None:
+    # NOW is a Sunday: Mon 12:00am is midnight starting Monday 2026-10-26.
+    assert _at("resets Mon 12:00am") == datetime(2026, 10, 26, 0, 0, tzinfo=UTC)
+
+
+def test_month_day_form() -> None:
+    assert _at("resets Sep 15 at 7pm") == datetime(2027, 9, 15, 19, 0, tzinfo=UTC)
+    assert _at("resets Nov 2 at 7pm") == datetime(2026, 11, 2, 19, 0, tzinfo=UTC)
+
+
+def test_half_past_noon() -> None:
+    assert _at("resets 12:30pm") == datetime(2026, 10, 26, 12, 30, tzinfo=UTC)
+
+
+def test_trailing_pane_text_is_not_part_of_the_clause() -> None:
+    reset = parse_reset("resets 7:20pm… esc to interrupt", NOW)
+    assert reset is not None and reset.raw == "7:20pm"
+
+
+# --- rollover ----------------------------------------------------------------
+
+
+def test_time_already_past_today_rolls_past_midnight() -> None:
+    late = datetime(2026, 10, 25, 23, 30, tzinfo=UTC)
+    assert _at("resets 1:15am", late) == datetime(2026, 10, 26, 1, 15, tzinfo=UTC)
+
+
+def test_the_reset_is_strictly_after_now() -> None:
+    exact = datetime(2026, 10, 25, 19, 20, tzinfo=UTC)
+    assert _at("resets 7:20pm", exact) == datetime(2026, 10, 26, 19, 20, tzinfo=UTC)
+
+
+def test_same_weekday_already_past_rolls_a_week() -> None:
+    sunday_noon = datetime(2026, 10, 25, 12, 0, tzinfo=UTC)
+    assert _at("resets Sun 9am", sunday_noon) == datetime(2026, 11, 1, 9, 0, tzinfo=UTC)
+    assert _at("resets Sun 1pm", sunday_noon) == datetime(2026, 10, 25, 13, 0, tzinfo=UTC)
+
+
+def test_weekday_later_this_week() -> None:
+    assert _at("resets Wed 8am") == datetime(2026, 10, 28, 8, 0, tzinfo=UTC)
+
+
+def test_month_day_past_rolls_into_next_year() -> None:
+    new_years_eve = datetime(2026, 12, 31, 22, 0, tzinfo=UTC)
+    assert _at("resets Jan 1 at 9am", new_years_eve) == datetime(2027, 1, 1, 9, 0, tzinfo=UTC)
+    assert _at("resets Dec 31 at 9pm", new_years_eve) == datetime(2027, 12, 31, 21, 0, tzinfo=UTC)
+
+
+def test_feb_29_lands_on_the_next_leap_year() -> None:
+    assert _at("resets Feb 29 at 9am") == datetime(2028, 2, 29, 9, 0, tzinfo=UTC)
+
+
+# --- 12am / 12pm -------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    ("clause", "hour"),
+    [("12am", 0), ("12:05am", 0), ("12pm", 12), ("12:05pm", 12), ("1am", 1), ("11pm", 23)],
+)
+def test_twelve_oclock_edges(clause: str, hour: int) -> None:
+    at = _at(f"resets {clause}", datetime(2026, 10, 25, 0, 0, 0, 1, tzinfo=UTC))
+    assert at.hour == hour
+
+
+# --- no clause / garbage -----------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "line",
+    ["", "You've used 90% of your limit", "presets 7pm", "resets", "resets ", "the resets"],
+)
+def test_no_clause_is_none(line: str) -> None:
+    assert parse_reset(line, NOW) is None
+
+
+@pytest.mark.parametrize(
+    ("line", "raw"),
+    [
+        ("resets soon", "soon"),
+        ("resets 7:2", "7:2"),
+        ("resets 19:20", "19:20"),
+        ("resets 13pm", "13pm"),
+        ("resets 0am", "0am"),
+        ("resets 7:61pm", "7:61pm"),
+        ("resets Sep 31 at 7pm", "Sep 31 at 7pm"),
+        ("resets 7pm (GMT+7)", "7pm (GMT+7)"),
+        ("resets 7pmx", "7pmx"),
+    ],
+)
+def test_garbage_is_unparsed_and_keeps_raw(line: str, raw: str) -> None:
+    reset = parse_reset(line, NOW)
+    assert reset == UsageReset(raw=raw, at=None, unresolved="unparsed")
+    assert reset.value == raw
+
+
+def test_unparsed_raw_is_truncated() -> None:
+    reset = parse_reset("resets " + "x" * 500, NOW)
+    assert reset is not None and reset.unresolved == "unparsed"
+    assert len(reset.raw) == 80
+
+
+# --- zone unavailable --------------------------------------------------------
+
+
+def test_zone_not_found_is_zone_unavailable(fixed_zones: dict[str, tzinfo]) -> None:
+    reset = parse_reset("resets 7pm (Mars/Olympus_Mons)", NOW)
+    assert reset == UsageReset(
+        raw="7pm (Mars/Olympus_Mons)", at=None, unresolved="zone-unavailable"
+    )
+    assert reset.value == "7pm (Mars/Olympus_Mons)"
+
+
+@pytest.mark.parametrize("exc", [ZoneInfoNotFoundError("x"), ValueError("bad key"), OSError()])
+def test_any_zone_lookup_fault_is_zone_unavailable(
+    monkeypatch: pytest.MonkeyPatch, exc: Exception
+) -> None:
+    def lookup(name: str) -> tzinfo:
+        raise exc
+
+    monkeypatch.setattr(usagereset, "ZoneInfo", lookup)
+    reset = parse_reset("resets 6pm (Europe/Warsaw)", NOW)
+    assert reset is not None
+    assert (reset.at, reset.unresolved) == (None, "zone-unavailable")
+
+
+def test_real_zone_database_when_present() -> None:
+    """The unpatched lookup, end to end, over a DST change (skipped without
+    tzdata): Warsaw leaves summer time on 2026-10-25, so 6pm there today is
+    17:00 UTC."""
+    try:
+        ZoneInfo("Europe/Warsaw")
+    except ZoneInfoNotFoundError:
+        pytest.skip("no tzdata for Europe/Warsaw on this host")
+    at = _at("resets 6pm (Europe/Warsaw)", datetime(2026, 10, 25, 10, 0, tzinfo=UTC))
+    assert at.astimezone(UTC) == datetime(2026, 10, 25, 17, 0, tzinfo=UTC)

From 939fd3fec50c58ee49831e625fd01b2768cd018e Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Sun, 25 Oct 2026 13:21:08 -0700
Subject: [PATCH 4/8] docs: document usage-limit patterns, the quota wait and
 limits.quota_wait_max_min

---
 CHANGELOG.md                    | 23 ++++++------
 docs/FEATURES.md                | 11 +++---
 docs/adapter-authoring-guide.md | 64 +++++++++++++++++++++++++++++++++
 docs/escalations-guide.md       | 17 +++++++++
 docs/reference/run-state.md     | 20 +++++------
 docs/tui-guide.md               |  5 ++-
 6 files changed, 112 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 521a90c2f..5fc4bdaa0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,16 +10,13 @@ breaking changes may land in a minor release.
 ### Added
 
 - Add `limits.quota_wait_max_min` (default 300; 0 = off): while the visible pane shows
-  Claude Code waiting out a usage-window reset and the transcript is idle, the session
-  timeout stands still and the stall nudge is held, so the session no longer burns
-  `session_timeout_min` behind the limit and can finish after the CLI's own
-  auto-continue. Past the cap the session pauses with a usage-limit reason.
-  `heartbeat.json` gains `quota_waiting` / `quota_wait_s`, `session-end` gains
-  `quota_wait_s`, and the journal gains `quota-wait-started` / `-ended` / `-cap`.
-  The line's `resets …` time is parsed into the pause reason (`; resets <time>`),
-  `heartbeat.json` (`quota_resets_at`), `session-end` (`usage_limit_resets`) and the
-  TUI header, which shows `quota wait` instead of `idle`. A reset beyond the remaining
-  cap skips the wait and pauses at once.
+  Claude Code waiting out a usage-window reset and the transcript is idle, freeze the
+  session timeout and hold the stall nudge, so the session finishes after the CLI's own
+  auto-continue. Past the cap, or when the parsed reset lies beyond it, pause with a
+  usage-limit reason. Surface the wait and the reset time in `heartbeat.json`
+  (`quota_waiting`, `quota_wait_s`, `quota_resets_at`), `session-end` (`quota_wait_s`,
+  `usage_limit_resets`), the journal (`quota-wait-*`), the pause reason
+  (`; resets <time>`) and the TUI header (`quota wait`).
 - Add the experimental `tickets` work source for BMAD v7 initiative ticket trees
   (`[stories] source = "tickets"`): dispatch `bmad-build-auto ticket <ref>` in initiative
   build order, verify each plan at `built`, and mark it `done` through `tickets.py mark`
@@ -186,9 +183,9 @@ breaking changes may land in a minor release.
 
 ### Fixed
 
-- Pause a Claude session blocked by a usage limit (credit exhaustion or a session-window
-  limit seen on the live pane) with a `usage limit:` reason instead of charging it a dev
-  attempt; a live sighting is exempt from the token veto. New profile fields
+- Pause a Claude session seen blocked by a usage limit (credit exhaustion or a
+  session-window limit) with a `usage limit:` reason instead of charging a dev attempt;
+  a live pane sighting is exempt from the token veto. Add the profile fields
   `usage_limit_patterns` and `usage_wait_patterns`, seeded from lines captured in
   community reports (#610).
 - Read an epic the initiative declares but has not sliced yet: `status` no longer
diff --git a/docs/FEATURES.md b/docs/FEATURES.md
index c162da3f3..2f8f67ee0 100644
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -101,8 +101,9 @@ bmad-loop drives a BMAD sprint unattended: a deterministic Python loop launches
   - A session silent for `dev_stall_grace_s` (default 600) gets up to `dev_stall_nudges` wake nudges, then ends `stalled` and is charged as a failed attempt.
   - Every dev and review session ends as `timeout` after `[limits] session_timeout_min` (default 90).
   - A dev session that did no work, or any session parked on a prompt only a human should answer, pauses the run instead of being charged.
+  - While the visible pane shows the coding CLI waiting out a usage-limit reset and the transcript is idle, the session timeout is frozen and the stall nudge held, for at most `[limits] quota_wait_max_min` (default 300; 0 = off) cumulative minutes per session; past the cap, or when the parsed reset lies beyond it, the session pauses with a usage-limit reason.
   - Before an attempt is reset, its commits go to an `attempt-preserve/<run>-<tip8>` branch and uncommitted work to a `refs/attempt-preserve-dirty/*` snapshot.
-- **Config:** `[limits] max_dev_attempts`, `[limits] max_review_cycles`, `[limits] session_timeout_min`, `[limits] dev_stall_grace_s`, `[limits] dev_stall_nudges`, `[limits] dev_stall_nudges_cap`, `[scm] preserve_keep`
+- **Config:** `[limits] max_dev_attempts`, `[limits] max_review_cycles`, `[limits] session_timeout_min`, `[limits] dev_stall_grace_s`, `[limits] dev_stall_nudges`, `[limits] dev_stall_nudges_cap`, `[limits] quota_wait_max_min`, `[scm] preserve_keep`
 - **Tested by:** `tests/test_escalation.py`, `tests/test_engine.py`, `tests/test_generic_tmux.py`, `tests/test_verify.py`, `tests/test_recovery_flow.py`
 - **Docs:** [Preserved attempts](escalations-guide.md#preserved-attempts), [[limits] reference](reference/configuration.md#limits), [[scm] reference](reference/configuration.md#scm)
 
@@ -161,9 +162,11 @@ bmad-loop drives a BMAD sprint unattended: a deterministic Python loop launches
   - A non-completed session whose log tail matches its profile's `env_fault_patterns` pauses instead of spending a dev attempt.
   - opencode is classified from model-free files only: the server's stdout, plus on OpenCode 2.x the adapter-written `provider-errors.log` (one line per provider-error event). Its 2.x patterns cover the `provider.rate-limit`, `provider.quota` and `provider.transport` error types.
   - A pattern match is overruled when the session's tracked token usage is nonzero; that session is charged like any failure.
-- **Config:** `[environment] probes`, `[environment] probe_timeout_s`, `[verify] env_fault_rc`; profile key `env_fault_patterns`
-- **Tested by:** `tests/test_engine.py`, `tests/test_escalation.py`, `tests/test_env_fault_patterns.py`, `tests/test_env_fault.py`, `tests/test_generic_tmux.py`, `tests/test_opencode_http.py`
-- **Docs:** [Environment faults](escalations-guide.md#environment-faults), [[environment] reference](reference/configuration.md#environment), [[verify] reference](reference/configuration.md#verify), [Profile field reference](adapter-authoring-guide.md#cliprofile)
+  - A session whose visible pane shows a usage-limit line from its profile's `usage_limit_patterns` or `usage_wait_patterns`, at stall-grace expiry or when the timeout fires, pauses with a `usage limit:` reason and is never charged, whatever its token usage; the same line found only in the log tail stays subject to the overrule.
+  - When the usage-limit line names a reset time, the pause reason ends its evidence with `; resets <time>` (ISO-8601 when the time resolves, the raw text otherwise).
+- **Config:** `[environment] probes`, `[environment] probe_timeout_s`, `[verify] env_fault_rc`, `[limits] quota_wait_max_min`; profile keys `env_fault_patterns`, `usage_limit_patterns`, `usage_wait_patterns`
+- **Tested by:** `tests/test_engine.py`, `tests/test_escalation.py`, `tests/test_env_fault_patterns.py`, `tests/test_env_fault.py`, `tests/test_generic_tmux.py`, `tests/test_opencode_http.py`, `tests/test_usagereset.py`
+- **Docs:** [Environment faults](escalations-guide.md#environment-faults), [Usage-limit pauses](escalations-guide.md#usage-limit-pauses), [Usage-limit signals](adapter-authoring-guide.md#usage-limit-signals), [[environment] reference](reference/configuration.md#environment), [[verify] reference](reference/configuration.md#verify), [Profile field reference](adapter-authoring-guide.md#cliprofile)
 
 ### Resumable runs and graceful stop
 
diff --git a/docs/adapter-authoring-guide.md b/docs/adapter-authoring-guide.md
index ac5a3da67..24dd0bc91 100644
--- a/docs/adapter-authoring-guide.md
+++ b/docs/adapter-authoring-guide.md
@@ -323,6 +323,8 @@ a new `name` extends the set. The aliases `claude-code-tmux` and `opencode` reso
 | `seed_files`                       |          | `[]`                                                                           | Project-relative gitignored files copied into each provisioned worktree. Must stay inside the project.                                                                                                            |
 | `env_fault_patterns`               |          | `[]`                                                                           | Regexes that classify a non-completed session as an environment fault. See [Environment-fault patterns](#environment-fault-patterns).                                                                             |
 | `parked_prompt_patterns`           |          | `[]`                                                                           | Regexes matched against the visible pane at each stall-grace expiry. See [Parked-session signals](#parked-session-signals).                                                                                       |
+| `usage_limit_patterns`             |          | `[]`                                                                           | Regexes for a usage-limit line the CLI stays blocked behind until an operator acts. See [Usage-limit signals](#usage-limit-signals).                                                                              |
+| `usage_wait_patterns`              |          | `[]`                                                                           | Regexes for a usage-limit line the CLI waits out and continues from by itself. Disjoint from `usage_limit_patterns`. See [Usage-limit signals](#usage-limit-signals).                                             |
 | `[workspace_trust]`                |          | unset                                                                          | The [`WorkspaceTrustSpec`](#workspacetrustspec-the-workspace_trust-table) table. Unset: nothing under `~` is read or written.                                                                                     |
 | `session_id_flag`                  |          | `""`                                                                           | Launch flag for a caller-chosen session id (claude: `--session-id`). The generic adapter appends `[flag, uuid4]` and pins attribution to that id.                                                                 |
 | `subagent_transcript_dir`          |          | derived from `usage_parser` (`{stem}/subagents` for `claude-jsonl`, else `""`) | Subagent transcript tree beside the transcript, walked recursively and stat-only; its writes count as idle-notice activity. Must contain `{stem}` (the transcript's filename stem) and stay relative; `""` = off. |
@@ -426,6 +428,10 @@ is in [Environment faults](escalations-guide.md#environment-faults).
 - Seeded for `claude` (connection loss and two captured provider 5xx errors) and
   `opencode` (provider quota/rate-limit and connection on 1.x; `provider.rate-limit`,
   `provider.quota` and `provider.transport` events on 2.x). Empty means inert.
+- The tail scan also covers `usage_limit_patterns` and `usage_wait_patterns` as ordinary
+  pattern families, under the same token-usage overrule: a session that got past a limit
+  and later failed for another reason is charged. Only a live pane sighting of a usage
+  line exempts a session from the overrule; see [Usage-limit signals](#usage-limit-signals).
 
 ### Parked-session signals
 
@@ -455,6 +461,64 @@ turn without a result and sits idle pauses as parked instead of being nudged. A
 overlay (`.bmad-loop/profiles/claude.toml`) that drops `idle_prompt` from
 `[hooks.notification_types]` restores the wake nudge.
 
+### Usage-limit signals
+
+A CLI stopped by a subscription or credit limit either stays blocked until someone acts
+(credit exhaustion) or waits for the limit's reset and continues by itself (a
+session-window limit under Claude Code's auto-continue). Two opt-in profile lists name
+those lines, both matched line by line against the ANSI-stripped visible pane:
+
+- **`usage_limit_patterns`**: the CLI is blocked and will not continue on its own.
+- **`usage_wait_patterns`**: the CLI is blocked and waiting for a reset it continues from.
+
+The lists are disjoint by contract; "usage-limited" means either one matched. They follow
+the env-fault evidentiary bar: reproduce the captured sentence prefix (never a bare
+`session limit`, `resets` or `usage credits`), use single-character classes so a pattern
+cannot match its own profile line, and seed only lines captured off the CLI's screen. The
+shipped `claude` profile seeds one line in each list; every other profile leaves both
+empty, which keeps them inert.
+
+**At stall-grace expiry** the pane is captured once and checked against the parked
+patterns and both usage lists. A usage match withholds the nudge (even when a hook latch
+such as `idle_prompt` is set, since an idle CLI behind a limit latches exactly that) and
+ends the session `stalled` + `parked` with `SessionResult.usage_limited` holding the
+matched evidence. **When the session timeout fires**, one capture against both lists sets
+`usage_limited` on the `timeout` result. A dead window is never usage-limited.
+
+A `usage_limited` result is classified as an environment fault with no token-usage
+overrule and no tail scan, and pauses with a `usage limit:` reason (see
+[Environment faults](escalations-guide.md#environment-faults)). When the matched line
+carries a `resets <time>` clause, the time is parsed (`H[:MM]am|pm`, optionally preceded by
+a weekday or `<Mon> <D> at` and followed by a ` (<Area/City>)` zone) into
+`usage_limit_resets`: ISO-8601 when it resolves, otherwise the raw clause, with a
+`usage-reset-unparsed` lifecycle crumb (`reason` is `unparsed`, or `zone-unavailable` when
+the host has no tz data for the named zone).
+
+**The quota wait.** With `[limits] quota_wait_max_min` above 0 (default 300) and
+`usage_wait_patterns` non-empty, the generic adapter admits a wait at a heartbeat when all
+of these hold: the transcript has been idle for at least 90 s, no tool call is open, the
+visible pane matches `usage_wait_patterns`, no `QuotaPrompt` or `PermissionPrompt` latch is
+set, and the session's cumulative wait is under the cap. While waiting:
+
+- the session timeout is frozen on every tick, at no less than 120 s remaining;
+- a stall-grace expiry re-arms the grace with no nudge (a `QuotaPrompt` or
+  `PermissionPrompt` latch still parks; an `IdlePrompt` latch never ends a wait);
+- a `Stop` without a result withholds the stop nudge (`stop-nudge-withheld`,
+  `reason="quota-wait"`); a `Stop` with a result completes normally;
+- the token-budget grace keeps counting, because a crossed budget is real spend.
+
+The wait ends when the transcript moves again (the timeout resumes from where it was
+frozen) or when a `QuotaPrompt`/`PermissionPrompt` latch arrives. The pane no longer
+matching does not end it, since the line can scroll away. At the cap, measured on both the
+monotonic and the wall clock so a host suspend cannot stretch it, the session ends
+`stalled` + `parked` + `usage_limited` (`quota-wait-cap`). A line whose parsed reset lies
+beyond the remaining cap is not waited on: the session ends the same way at once
+(`quota-wait-skipped`, `reason="reset-beyond-cap"`). An unresolved reset is admitted, and
+the cap bounds it.
+
+The `opencode-http` adapter runs its own wait loop with no pane, so neither the usage gate
+nor the quota wait applies there.
+
 ### Worked TOML — copilot
 
 The shipped `copilot` profile uses the non-default tuning knobs and a camelCase event map,
diff --git a/docs/escalations-guide.md b/docs/escalations-guide.md
index 8c1f82732..84f57288b 100644
--- a/docs/escalations-guide.md
+++ b/docs/escalations-guide.md
@@ -222,6 +222,23 @@ What to do depends on where it hit:
 | `probe:decision:dev`, `probe:decision:fix`, `probe:claim:dev`, `probe:claim:fix`                 | yes, if the latest dev session completed       |
 | `probe:dispatch:dev`, `probe:dispatch:review`                                                    | no: it is an `environment` pause; use `resume` |
 
+### Usage-limit pauses
+
+A session the adapter saw blocked by a coding-CLI usage limit (out of credits, or a session-window limit) pauses with a reason of the form:
+
+```text
+usage limit: dev session stalled (<pane line>; resets <time>; the coding CLI is blocked by a usage limit — add credits, switch model or wait for the reset, then bmad-loop resolve <run>)
+```
+
+The attempt is not charged, whatever tokens the session used before the limit hit: the line was on screen when the session ended. `<pane line>` is the matched line from the CLI's screen. `; resets <time>` appears only when that line names a reset: an ISO-8601 time when it resolves, otherwise the text as printed (for example when the host has no time-zone data for the zone the CLI named).
+
+To recover:
+
+1. Clear the limit: add credits, switch the session's model (`[adapter] model`, or the stage's `[adapter.<stage>]`), or wait until the reset time.
+2. `bmad-loop resolve <run-id> --no-interactive` re-arms the story with a fresh attempt budget and resumes. The spec needs no fix.
+
+A session-window limit the CLI waits out by itself does not pause at all at first. While the pane shows that wait and the transcript is idle, the session timeout stands still and no stall nudge is sent, so the session finishes after the CLI continues. `[limits] quota_wait_max_min` (default 300, one five-hour window; 0 = off) caps the minutes one session may spend waiting. Past the cap, or when the parsed reset already lies beyond what is left of it, the session pauses with the reason above. A heartbeat shows the wait as `quota_waiting` / `quota_wait_s` / `quota_resets_at`, and the TUI header as `quota wait`.
+
 ## Worktree merge-back failures
 
 Under `[scm] isolation = "worktree"`, each story merges back into the target branch in the main checkout. When the merge fails, the unit escalates: its branch `bmad-loop/<run-id>[/<story>]` and worktree are kept, the diff is saved to `.bmad-loop/runs/<run-id>/failed/<unit>/changes.patch`, and the run pauses at `escalation`.
diff --git a/docs/reference/run-state.md b/docs/reference/run-state.md
index 07f930b35..a645f8735 100644
--- a/docs/reference/run-state.md
+++ b/docs/reference/run-state.md
@@ -83,7 +83,7 @@ The opencode adapter's environment-fault classifier scans `<task_id>.server.out`
 
 - **`state.json`** — the serialized run state (stories, phases, tokens, the `finished` / `stopped` / `crashed` flags, and `paused_reason` with the pause context). Written atomically under a per-run lock, through the pinned run-directory descriptor above; `bmad-loop status` reads it.
 - **`journal.jsonl`** — append-only, one JSON object per line with `ts` and `kind`; the first entry is `run-start` (after one `journal-unpinned` row on a filesystem that reports no inode numbers). Lines end in LF on every platform. Written through the pinned run-directory descriptor by the engine, and by commands that act on the run (for example `stop`, `resume`, `resolve`). From the first session launch on, lines carry `log_task` / `log_pos`, pointing into the most recent session's log.
-- **`heartbeat.json`** (in `tasks/<task_id>/`) — the wait loop's proof of life, overwritten at most every 30 seconds while a session runs: remaining budget, stall-recovery state and probe or sampling failure counts.
+- **`heartbeat.json`** (in `tasks/<task_id>/`) — the wait loop's proof of life, overwritten at most every 30 seconds while a session runs: remaining budget, stall-recovery state and probe or sampling failure counts. A session that can wait out a usage-limit reset (`[limits] quota_wait_max_min` above 0 and a profile with `usage_wait_patterns`) also carries `quota_waiting` and `quota_wait_s` (cumulative seconds waited), plus `quota_resets_at` while it waits on a line that named a reset.
 
 `state.json` records the run's work source. A bmad-loop that does not know that source refuses to resume the run rather than drive it as a sprint run, so finish or abandon a run before downgrading bmad-loop.
 
@@ -114,15 +114,15 @@ A store that is its own git repository (T3 nested, T4 external) then gets a plan
 
 `tasks/<task_id>/` is created per agent session. The task id is `<story_key>-<part>-<n>`, where `part` is `dev`, `review`, `triage` or a workflow label and `n` is the attempt or review cycle; a re-armed story adds `-g<generation>`.
 
-| File                      | Written by        | Contents                                                                                                                                                         |
-| ------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `prompt.txt`              | adapter           | the session prompt, rewritten each launch                                                                                                                        |
-| `result.json`             | session           | the session's result contract (verdict, escalations)                                                                                                             |
-| `escalation.json`         | sweep session     | escalations raised during triage                                                                                                                                 |
-| `heartbeat.json`          | adapter           | proof of life (above)                                                                                                                                            |
-| `resultless-stops.jsonl`  | built-in adapters | one line per Stop event whose result could not be read                                                                                                           |
-| `session-lifecycle.jsonl` | built-in adapters | one line per lifecycle event (timeout, budget trip, environment-fault classification)                                                                            |
-| `messages.json`           | opencode adapter  | raw server messages, kept as the transcript; the shape is the server's own (1.x: each message's info and parts; 2.x: user/assistant/idle messages, oldest first) |
+| File                      | Written by        | Contents                                                                                                                                                                                     |
+| ------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prompt.txt`              | adapter           | the session prompt, rewritten each launch                                                                                                                                                    |
+| `result.json`             | session           | the session's result contract (verdict, escalations)                                                                                                                                         |
+| `escalation.json`         | sweep session     | escalations raised during triage                                                                                                                                                             |
+| `heartbeat.json`          | adapter           | proof of life (above)                                                                                                                                                                        |
+| `resultless-stops.jsonl`  | built-in adapters | one line per Stop event whose result could not be read                                                                                                                                       |
+| `session-lifecycle.jsonl` | built-in adapters | one line per lifecycle event (timeout, budget trip, environment-fault classification, usage-limit quota wait: `quota-wait-started` / `-ended` / `-cap` / `-skipped`, `usage-reset-unparsed`) |
+| `messages.json`           | opencode adapter  | raw server messages, kept as the transcript; the shape is the server's own (1.x: each message's info and parts; 2.x: user/assistant/idle messages, oldest first)                             |
 
 `result.json` and `escalation.json` are the shared cycle artifacts (`journal.TASK_CYCLE_ARTIFACTS`). Both built-in adapters delete them before launching a session, so a reused task id never inherits a previous session's result. Adapters refuse a task directory that is a symlink or junction, and an adapter-written file (heartbeat, breadcrumb logs, `messages.json`, session logs) that is a link or special file.
 
diff --git a/docs/tui-guide.md b/docs/tui-guide.md
index 73116b042..6e20f88b5 100644
--- a/docs/tui-guide.md
+++ b/docs/tui-guide.md
@@ -206,7 +206,10 @@ default is used; `role` is the session's stage, such as `dev`, `review`,
 `· idle <age>` once the session's transcript (and any subagent transcripts its
 profile declares) has been quiet past
 `limits.dev_stall_grace_s`, followed by `· in <tool>` when the session is
-waiting on a tool call (`unknown` if the transcript could not be read). Between sessions it shows the run's configured
+waiting on a tool call (`unknown` if the transcript could not be read). A session
+waiting out a usage-limit reset shows `· quota wait <age>` in place of `· idle <age>`,
+followed by `· resets <Ddd HH:MM>` (local time) when the limit line named a reset that
+resolved, or the reset text as printed when it did not. Between sessions it shows the run's configured
 adapters from its policy snapshot. A run with no snapshot shows no agent line;
 an unreadable session identity shows `agent unreadable — <fault>`.
 

From 1371db926298e6c619d9a889585f983818d7acd9 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Sun, 25 Oct 2026 13:31:32 -0700
Subject: [PATCH 5/8] fix(adapters): keep a working session's timeout out of
 the usage-limit verdict

A usage-limit line left on screen by a session that recovered and kept
working labelled its later timeout usage-limited, which the env-fault
classifier exempts from the token veto: the run paused without charging and
asked the operator to resolve a limit long gone. The timeout path now applies
the quota wait's activity tests (transcript written within QUOTA_WAIT_IDLE_S,
or an unanswered tool call) before taking the pane's word.
---
 docs/FEATURES.md                  |  2 +-
 docs/adapter-authoring-guide.md   |  5 ++++-
 src/bmad_loop/adapters/generic.py | 20 +++++++++++++++++++-
 tests/test_generic_tmux.py        | 15 +++++++++++----
 4 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/docs/FEATURES.md b/docs/FEATURES.md
index 2f8f67ee0..336c9030a 100644
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -162,7 +162,7 @@ bmad-loop drives a BMAD sprint unattended: a deterministic Python loop launches
   - A non-completed session whose log tail matches its profile's `env_fault_patterns` pauses instead of spending a dev attempt.
   - opencode is classified from model-free files only: the server's stdout, plus on OpenCode 2.x the adapter-written `provider-errors.log` (one line per provider-error event). Its 2.x patterns cover the `provider.rate-limit`, `provider.quota` and `provider.transport` error types.
   - A pattern match is overruled when the session's tracked token usage is nonzero; that session is charged like any failure.
-  - A session whose visible pane shows a usage-limit line from its profile's `usage_limit_patterns` or `usage_wait_patterns`, at stall-grace expiry or when the timeout fires, pauses with a `usage limit:` reason and is never charged, whatever its token usage; the same line found only in the log tail stays subject to the overrule.
+  - A session whose visible pane shows a usage-limit line from its profile's `usage_limit_patterns` or `usage_wait_patterns`, at stall-grace expiry or when the timeout fires on an idle session, pauses with a `usage limit:` reason and is never charged, whatever its token usage; the same line found only in the log tail stays subject to the overrule.
   - When the usage-limit line names a reset time, the pause reason ends its evidence with `; resets <time>` (ISO-8601 when the time resolves, the raw text otherwise).
 - **Config:** `[environment] probes`, `[environment] probe_timeout_s`, `[verify] env_fault_rc`, `[limits] quota_wait_max_min`; profile keys `env_fault_patterns`, `usage_limit_patterns`, `usage_wait_patterns`
 - **Tested by:** `tests/test_engine.py`, `tests/test_escalation.py`, `tests/test_env_fault_patterns.py`, `tests/test_env_fault.py`, `tests/test_generic_tmux.py`, `tests/test_opencode_http.py`, `tests/test_usagereset.py`
diff --git a/docs/adapter-authoring-guide.md b/docs/adapter-authoring-guide.md
index 24dd0bc91..1b72bbf66 100644
--- a/docs/adapter-authoring-guide.md
+++ b/docs/adapter-authoring-guide.md
@@ -483,7 +483,10 @@ patterns and both usage lists. A usage match withholds the nudge (even when a ho
 such as `idle_prompt` is set, since an idle CLI behind a limit latches exactly that) and
 ends the session `stalled` + `parked` with `SessionResult.usage_limited` holding the
 matched evidence. **When the session timeout fires**, one capture against both lists sets
-`usage_limited` on the `timeout` result. A dead window is never usage-limited.
+`usage_limited` on the `timeout` result, unless the session is visibly working: a
+transcript written within the last 90 s (as of the last heartbeat) or an unanswered tool
+call means the line is left over from a limit it recovered from, and the timeout is an
+ordinary one. A dead window is never usage-limited.
 
 A `usage_limited` result is classified as an environment fault with no token-usage
 overrule and no tail scan, and pauses with a `usage limit:` reason (see
diff --git a/src/bmad_loop/adapters/generic.py b/src/bmad_loop/adapters/generic.py
index 29291f892..e2a6774c2 100644
--- a/src/bmad_loop/adapters/generic.py
+++ b/src/bmad_loop/adapters/generic.py
@@ -1616,9 +1616,27 @@ def stall_exit(
                 # failed attempt. A dead window is never usage-limited (the CLI
                 # is gone, though a remain-on-exit pane still captures), so a
                 # match is confirmed alive first; a probe fault reads "not dead".
+                # A visible line alone is not proof the CLI is still blocked:
+                # one that recovered and kept working can leave it on screen.
+                # The quota wait's activity tests apply here too — a transcript
+                # written inside QUOTA_WAIT_IDLE_S (as of the last heartbeat
+                # sample) or an unanswered tool call is a working session, and
+                # its timeout is an ordinary one, charged as before #610 (so is
+                # a tool scan that faults). Unknown activity (no transcript
+                # named yet, or no sample) keeps the pane's word.
                 (usage_hit,) = self._pane_evidence(handle, self._usage_pane_patterns)
                 usage_now = resets_now = None
-                if usage_hit is not None and self._probe_liveness(handle, "timeout") is not False:
+                if (
+                    usage_hit is not None
+                    and self._probe_liveness(handle, "timeout") is not False
+                    and not (
+                        transcript_path
+                        and (
+                            (idle.idle_s is not None and idle.idle_s < QUOTA_WAIT_IDLE_S)
+                            or self._quota_wait_tool_open(handle, transcript_path)
+                        )
+                    )
+                ):
                     usage_now = usage_hit[0]
                     reset = self._usage_reset(handle, usage_hit[1], _local_now())
                     resets_now = reset.value if reset is not None else None
diff --git a/tests/test_generic_tmux.py b/tests/test_generic_tmux.py
index 1e72d7369..d88746ae1 100644
--- a/tests/test_generic_tmux.py
+++ b/tests/test_generic_tmux.py
@@ -12879,10 +12879,12 @@ def test_quota_wait_freezes_on_every_tick_not_only_heartbeats(tmp_path, monkeypa
 def test_quota_wait_needs_an_idle_transcript(tmp_path, monkeypatch):
     """The wait line on screen but a transcript still being written (a session
     that recovered and kept working, the line still on screen): no wait, and the
-    timeout fires on schedule.
+    timeout fires on schedule as an ordinary one, not usage-limited (#610's
+    veto exemption would otherwise pause the run for a limit long gone).
 
     Ablation: drop the `idle_s >= QUOTA_WAIT_IDLE_S` guard and a wait opens at
-    the first heartbeat."""
+    the first heartbeat; drop the timeout path's idle test and the verdict is
+    usage-limited."""
     q = _quota_adapter(tmp_path, monkeypatch)
 
     def script(call_n):
@@ -12891,6 +12893,8 @@ def script(call_n):
 
     result = _drive_quota(q, _quota_spec(tmp_path), script=script)
     assert result.status == "timeout"
+    assert result.usage_limited is None
+    assert result.usage_limit_resets is None
     assert result.quota_wait_s == 0.0
     assert q.quota_kinds() == []
     assert _lifecycle_events(q.adapter, "quota-wait-started") == []
@@ -12899,13 +12903,16 @@ def script(call_n):
 def test_quota_wait_not_admitted_with_an_open_tool_call(tmp_path, monkeypatch):
     """An idle transcript whose last line opens a `Bash` call: the CLI is waiting
     on its own foreground tool, not on a reset, whatever the pane still shows.
-    No wait; the timeout fires on schedule.
+    No wait; the timeout fires on schedule, and not as usage-limited: the open
+    call is still a working session when the clock runs out.
 
-    Ablation: drop the `_quota_wait_tool_open` guard and the wait opens."""
+    Ablation: drop the `_quota_wait_tool_open` guard and the wait opens; drop
+    it from the timeout path and the verdict is usage-limited."""
     q = _quota_adapter(tmp_path, monkeypatch)
     _grow(q.transcript, _tool_use("t1", "Bash", "2026-01-01T00:00:01Z"))
     result = _drive_quota(q, _quota_spec(tmp_path))
     assert result.status == "timeout"
+    assert result.usage_limited is None
     assert result.quota_wait_s == 0.0
     assert q.quota_kinds() == []
 

From b41d385e380d3acab200bf234946a467a32dbb50 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Sun, 25 Oct 2026 13:38:41 -0700
Subject: [PATCH 6/8] fix(adapters): resolve a zoneless usage-limit reset
 through the host zone's DST rules

_local_now() handed parse_reset an astimezone() datetime, whose fixed
offset was stretched over any DST change before the reset: a weekly
'Mon 12:00am' reset, or a 6am reset on the spring-forward night, came out
an hour off and could trip the reset-beyond-cap rule. _local_now() is now
naive and parse_reset resolves each naive candidate wall time with
astimezone(), which applies the host zone's transition rules.
---
 src/bmad_loop/adapters/generic.py | 12 +++---
 src/bmad_loop/usagereset.py       | 20 ++++++----
 tests/test_usagereset.py          | 61 +++++++++++++++++++++++++++++++
 3 files changed, 81 insertions(+), 12 deletions(-)

diff --git a/src/bmad_loop/adapters/generic.py b/src/bmad_loop/adapters/generic.py
index e2a6774c2..2d38b6e47 100644
--- a/src/bmad_loop/adapters/generic.py
+++ b/src/bmad_loop/adapters/generic.py
@@ -228,10 +228,12 @@ def total_s(self) -> float:
 
 
 def _local_now() -> datetime:
-    """The aware local "now" a usage-limit reset clause is resolved against
-    (#610). Read off this module's wall clock, so the reset moves with the
-    session's own clock (and a test steering that clock steers this too)."""
-    return datetime.fromtimestamp(time.time()).astimezone()
+    """The naive local "now" a usage-limit reset clause is resolved against
+    (#610). Naive so `parse_reset` resolves the reset through the host zone's
+    DST rules rather than today's fixed offset. Read off this module's wall
+    clock, so the reset moves with the session's own clock (and a test steering
+    that clock steers this too)."""
+    return datetime.fromtimestamp(time.time())
 
 
 # min spacing between heartbeat.json overwrites in wait_for_completion; the
@@ -1719,7 +1721,7 @@ def stall_exit(
                         if (
                             reset is not None
                             and reset.at is not None
-                            and (reset.at - local_now).total_seconds() > cap_left
+                            and (reset.at - local_now.astimezone()).total_seconds() > cap_left
                         ):
                             # Reset-beyond-cap (#610): the CLI will not continue
                             # before the cap would end the wait anyway, so don't
diff --git a/src/bmad_loop/usagereset.py b/src/bmad_loop/usagereset.py
index 925a75081..4480ed745 100644
--- a/src/bmad_loop/usagereset.py
+++ b/src/bmad_loop/usagereset.py
@@ -1,7 +1,7 @@
 """Parse the ``resets …`` clause of a coding CLI's usage-limit line (#610).
 
-Pure: no clock reads, no I/O beyond the stdlib zone database. The caller
-passes ``now`` (an aware local datetime) and the full pane line that a
+Pure: no clock reads, no I/O beyond the stdlib zone database and the host's
+local-time rules. The caller passes ``now`` and the full pane line that a
 ``usage_limit_patterns`` / ``usage_wait_patterns`` entry matched; the result
 feeds the pause reason, ``heartbeat.json`` (``quota_resets_at``), the
 ``session-end`` journal field ``usage_limit_resets`` and the quota wait's
@@ -15,7 +15,10 @@
 forms seen in the field: ``7:20pm``, ``12:50pm (Asia/Ho_Chi_Minh)``,
 ``6pm (Europe/Warsaw)``, ``Mon 12:00am``, ``Sep 15 at 7pm``. The reset is the
 next occurrence of that wall time strictly after ``now``: in the named zone
-when the clause names one, else in ``now``'s own zone.
+when the clause names one, else in ``now``'s own zone. A naive ``now`` means
+the host's local zone, resolved per candidate through its DST rules; an aware
+``now`` from ``astimezone()`` carries only today's fixed offset, which a reset
+across a DST change would get an hour wrong.
 
 Degrade contract: :func:`parse_reset` never raises. A line with no clause is
 ``None``. A clause it cannot resolve keeps its raw text with ``at=None`` and
@@ -98,9 +101,9 @@ def parse_reset(line: str, now: datetime) -> UsageReset | None:
         except (ZoneInfoNotFoundError, ValueError, OSError):
             return _unresolved(raw, "zone-unavailable")
     try:
-        local_now = now.astimezone(tz) if tz is not None else now
+        local_now = now.astimezone(tz)
         at = _next_occurrence(m, dtime(hour, minute), local_now, tz)
-    except (ValueError, OverflowError):
+    except (ValueError, OverflowError, OSError):
         return _unresolved(raw, "unparsed")
     if at is None:
         return _unresolved(raw, "unparsed")
@@ -115,10 +118,13 @@ def _next_occurrence(
     m: re.Match[str], wall: dtime, now: datetime, tz: tzinfo | None
 ) -> datetime | None:
     """The first ``wall`` time strictly after ``now`` on a date the clause
-    allows. Dates are built with ``datetime.combine`` in ``tz``, so a DST
-    change between now and the reset keeps the stated wall time."""
+    allows. Dates are built with ``datetime.combine`` in ``tz`` (or as host
+    local wall times when ``tz`` is None), so a DST change between now and the
+    reset keeps the stated wall time."""
 
     def at(day: date) -> datetime:
+        if tz is None:
+            return datetime.combine(day, wall).astimezone()
         return datetime.combine(day, wall, tzinfo=tz)
 
     today = now.date()
diff --git a/tests/test_usagereset.py b/tests/test_usagereset.py
index 08078a238..f4b316891 100644
--- a/tests/test_usagereset.py
+++ b/tests/test_usagereset.py
@@ -6,6 +6,9 @@
 
 from __future__ import annotations
 
+import os
+import time
+from collections.abc import Callable, Iterator
 from datetime import datetime, timedelta, timezone, tzinfo
 from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
@@ -203,3 +206,61 @@ def test_real_zone_database_when_present() -> None:
         pytest.skip("no tzdata for Europe/Warsaw on this host")
     at = _at("resets 6pm (Europe/Warsaw)", datetime(2026, 10, 25, 10, 0, tzinfo=UTC))
     assert at.astimezone(UTC) == datetime(2026, 10, 25, 17, 0, tzinfo=UTC)
+
+
+# --- a naive now resolves through the host zone's DST rules -----------------
+
+# Central European rules as a POSIX TZ string (no tzdata needed): +01 in winter,
+# +02 from the last Sunday of March 02:00 to the last Sunday of October 03:00.
+_CET = "CET-1CEST,M3.5.0,M10.5.0/3"
+
+
+@pytest.fixture
+def host_zone() -> Iterator[Callable[[str], None]]:
+    """Point the process's local zone at a TZ string, restored afterwards."""
+    if not hasattr(time, "tzset"):
+        pytest.skip("time.tzset is POSIX-only")
+    saved = os.environ.get("TZ")
+
+    def set_zone(tz: str) -> None:
+        os.environ["TZ"] = tz
+        time.tzset()
+
+    yield set_zone
+    if saved is None:
+        os.environ.pop("TZ", None)
+    else:
+        os.environ["TZ"] = saved
+    time.tzset()
+
+
+def test_naive_now_crosses_spring_forward(host_zone: Callable[[str], None]) -> None:
+    """00:30 on the night summer time starts: 6am is 06:00+02, 4.5 hours away —
+    not 06:00+01 (today's offset), which would read 5.5 and trip the cap."""
+    host_zone(_CET)
+    now = datetime(2026, 3, 29, 0, 30)
+    at = _at("resets 6am", now)
+    assert at.utcoffset() == timedelta(hours=2)
+    assert at - now.astimezone() == timedelta(hours=4, minutes=30)
+
+
+def test_naive_now_weekday_crosses_fall_back(host_zone: Callable[[str], None]) -> None:
+    """A weekly reset across the end of summer time keeps its wall time."""
+    host_zone(_CET)
+    at = _at("resets Mon 12:00am", datetime(2026, 10, 23, 12, 0))
+    assert at.utcoffset() == timedelta(hours=1)
+    assert at.astimezone(UTC) == datetime(2026, 10, 25, 23, 0, tzinfo=UTC)
+
+
+def test_adapter_local_now_resolves_through_dst(
+    host_zone: Callable[[str], None], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The generic adapter's `_local_now` feeds this resolution: it must stay
+    naive, or the reset is pinned to today's offset again."""
+    from bmad_loop.adapters import generic
+
+    host_zone(_CET)
+    # 2026-03-28 23:30 UTC = 00:30 CET on the night summer time starts.
+    monkeypatch.setattr(time, "time", lambda: datetime(2026, 3, 28, 23, 30, tzinfo=UTC).timestamp())
+    at = _at("resets 6am", generic._local_now())
+    assert at.astimezone(UTC) == datetime(2026, 3, 29, 4, 0, tzinfo=UTC)

From c70af79b7c5adf0a93da375ee7fec1cc1e5df25f Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Sun, 25 Oct 2026 13:49:00 -0700
Subject: [PATCH 7/8] fix(adapters): keep a spent usage-limit line from
 reopening a quota wait

A wait that ended because the transcript moved left its limit line on
screen in Claude's inline renderer. At the session's next idle stretch
that stale line could reopen a wait, or, once its reset had passed and
resolved to the next day, skip straight to a parked stall. It also
labelled a later stall or timeout usage-limited. The matched line of a
wait the CLI continued from is now spent (_QuotaWait.spent), and
_pane_evidence skips it at admission, stall-grace expiry and the timeout
look. A new limit prints a new line, which still opens a fresh wait.
---
 docs/adapter-authoring-guide.md   | 14 +++---
 src/bmad_loop/adapters/generic.py | 46 +++++++++++++----
 tests/test_generic_tmux.py        | 84 +++++++++++++++++++++++++++++++
 3 files changed, 128 insertions(+), 16 deletions(-)

diff --git a/docs/adapter-authoring-guide.md b/docs/adapter-authoring-guide.md
index 1b72bbf66..75bfcb69c 100644
--- a/docs/adapter-authoring-guide.md
+++ b/docs/adapter-authoring-guide.md
@@ -512,12 +512,14 @@ set, and the session's cumulative wait is under the cap. While waiting:
 
 The wait ends when the transcript moves again (the timeout resumes from where it was
 frozen) or when a `QuotaPrompt`/`PermissionPrompt` latch arrives. The pane no longer
-matching does not end it, since the line can scroll away. At the cap, measured on both the
-monotonic and the wall clock so a host suspend cannot stretch it, the session ends
-`stalled` + `parked` + `usage_limited` (`quota-wait-cap`). A line whose parsed reset lies
-beyond the remaining cap is not waited on: the session ends the same way at once
-(`quota-wait-skipped`, `reason="reset-beyond-cap"`). An unresolved reset is admitted, and
-the cap bounds it.
+matching does not end it, since the line can scroll away. A line the CLI continued from is
+spent: if it stays on screen, no live usage gate (admission, stall-grace expiry or the
+timeout look) takes it as evidence again, and a later limit has to print a new line. At
+the cap, measured on both the monotonic and the wall clock so a host suspend cannot
+stretch it, the session ends `stalled` + `parked` + `usage_limited` (`quota-wait-cap`). A
+line whose parsed reset lies beyond the remaining cap is not waited on: the session ends
+the same way at once (`quota-wait-skipped`, `reason="reset-beyond-cap"`). An unresolved
+reset is admitted, and the cap bounds it.
 
 The `opencode-http` adapter runs its own wait loop with no pane, so neither the usage gate
 nor the quota wait applies there.
diff --git a/src/bmad_loop/adapters/generic.py b/src/bmad_loop/adapters/generic.py
index 2d38b6e47..6054f75c7 100644
--- a/src/bmad_loop/adapters/generic.py
+++ b/src/bmad_loop/adapters/generic.py
@@ -208,7 +208,10 @@ class _QuotaWait:
     host suspend (monotonic frozen, wall running) cannot stretch the cap.
     `closed_s` sums the waits that already ended; `evidence` is the pane line
     that admitted the open one, `resets` its parsed reset (`UsageReset.value`,
-    #610), None when the line named none."""
+    #610), None when the line named none. `line` is the full matched pane line;
+    `spent` holds (stripped) the lines of waits the CLI continued from. Such a
+    line is left on screen by a limit that is over, so no live usage gate takes
+    it as evidence again; a later limit prints a new line."""
 
     waiting: bool = False
     started_mono: float = 0.0
@@ -217,6 +220,8 @@ class _QuotaWait:
     closed_s: float = 0.0
     evidence: str | None = None
     resets: str | None = None
+    line: str | None = None
+    spent: set[str] = dataclasses.field(default_factory=set)
 
     def open_s(self) -> float:
         if not self.waiting:
@@ -1625,8 +1630,11 @@ def stall_exit(
                 # sample) or an unanswered tool call is a working session, and
                 # its timeout is an ordinary one, charged as before #610 (so is
                 # a tool scan that faults). Unknown activity (no transcript
-                # named yet, or no sample) keeps the pane's word.
-                (usage_hit,) = self._pane_evidence(handle, self._usage_pane_patterns)
+                # named yet, or no sample) keeps the pane's word. A line a
+                # quota wait already continued from is no evidence at all.
+                (usage_hit,) = self._pane_evidence(
+                    handle, self._usage_pane_patterns, skip=quota.spent
+                )
                 usage_now = resets_now = None
                 if (
                     usage_hit is not None
@@ -1694,9 +1702,14 @@ def stall_exit(
                     # The transcript moved: the CLI continued after the reset.
                     # The timeout resumes from the remaining time frozen at
                     # admission. A pane that merely stopped matching does not
-                    # end the wait: the line can scroll away.
+                    # end the wait: the line can scroll away. The line it waited
+                    # on is spent: left on screen, it must not reopen a wait
+                    # (or park the session, its reset now read as the next
+                    # day's) at the next idle stretch of a working session.
                     if idle.idle_s is not None and idle.idle_s < QUOTA_WAIT_IDLE_S:
                         self._end_quota_wait(handle, quota, "transcript-active")
+                        if quota.line is not None:
+                            quota.spent.add(quota.line.strip())
                 elif (
                     quota_enabled
                     and transcript_path
@@ -1708,9 +1721,12 @@ def stall_exit(
                     # Admission (DW-396): an idle transcript, the wait line on
                     # the visible pane, and no unanswered tool call (a long
                     # foreground tool is a working session, whatever the pane
-                    # still shows). The pane look comes first: it is the
-                    # cheaper read, and a non-match skips the transcript scan.
-                    (wait_hit,) = self._pane_evidence(handle, self._usage_wait_patterns)
+                    # still shows), on a line no earlier wait continued from.
+                    # The pane look comes first: it is the cheaper read, and a
+                    # non-match skips the transcript scan.
+                    (wait_hit,) = self._pane_evidence(
+                        handle, self._usage_wait_patterns, skip=quota.spent
+                    )
                     if wait_hit is not None and not self._quota_wait_tool_open(
                         handle, transcript_path
                     ):
@@ -1756,6 +1772,7 @@ def stall_exit(
                         quota.frozen_remaining = frozen
                         quota.evidence = wait_hit[0]
                         quota.resets = resets
+                        quota.line = wait_hit[1]
                 if not saw_session_start and not session_start_noted:
                     session_start_noted = self._note_session_start_missing(
                         handle, now - loop_started
@@ -2068,12 +2085,14 @@ def stall_exit(
                     # too (a nudge can only reproduce the limit line), and the
                     # match is recorded as `usage_limited` even when the hook
                     # latch already supplied the parked evidence, since claude's
-                    # idle_prompt latches on exactly this kind of idle.
+                    # idle_prompt latches on exactly this kind of idle. A line a
+                    # quota wait already continued from matches nothing.
                     parked_now = parked_evidence
                     parked_hit, usage_hit = self._pane_evidence(
                         handle,
                         self._parked_prompt_patterns if parked_now is None else (),
                         self._usage_pane_patterns,
+                        skip=quota.spent,
                     )
                     if parked_now is None and parked_hit is not None:
                         parked_now = parked_hit[0]
@@ -2806,7 +2825,10 @@ def _parked_prompt_patterns(self) -> tuple[regex.Pattern[str], ...]:
         return tuple(regex.compile(p) for p in self.profile.parked_prompt_patterns)
 
     def _pane_evidence(
-        self, handle: SessionHandle, *pattern_sets: tuple[regex.Pattern[str], ...]
+        self,
+        handle: SessionHandle,
+        *pattern_sets: tuple[regex.Pattern[str], ...],
+        skip: set[str] | frozenset[str] = frozenset(),
     ) -> tuple[tuple[str, str] | None, ...]:
         """One look at the VISIBLE pane, matched against each pattern set: per
         set, ``(evidence, matched_line)`` for its first match (lines outer,
@@ -2824,7 +2846,9 @@ def _pane_evidence(
         ``parked-probe-failed`` crumb (``reason`` = ``capture-failed`` or
         ``match-timeout`` + its ``pattern``; ``error``) records that the look at
         the pane failed. Empty sets and a backend without ``capture_pane`` are
-        configuration, not faults: no capture, no crumb."""
+        configuration, not faults: no capture, no crumb. A line in ``skip``
+        (compared stripped) is never a match: the usage gates pass the lines of
+        quota waits the CLI already continued from (``_QuotaWait.spent``)."""
         none: tuple[tuple[str, str] | None, ...] = tuple(None for _ in pattern_sets)
         if not any(pattern_sets):
             return none
@@ -2844,6 +2868,8 @@ def _pane_evidence(
         if not isinstance(screen, str):
             return none
         lines = _ANSI_RE.sub("", screen.replace("\r", "\n")).split("\n")
+        if skip:
+            lines = [line for line in lines if line.strip() not in skip]
         return tuple(self._first_pane_match(handle, lines, pats) for pats in pattern_sets)
 
     def _first_pane_match(
diff --git a/tests/test_generic_tmux.py b/tests/test_generic_tmux.py
index d88746ae1..74d3fbd9e 100644
--- a/tests/test_generic_tmux.py
+++ b/tests/test_generic_tmux.py
@@ -13150,6 +13150,90 @@ def script(call_n):
     assert result.quota_wait_s == 120.0
 
 
+def test_spent_wait_line_does_not_reopen_a_wait(tmp_path, monkeypatch):
+    """The CLI continues after the reset (the wait ends at mono 1210), writes once,
+    then goes quiet for longer than QUOTA_WAIT_IDLE_S with the old wait line still
+    on screen and the local clock past its 7:20pm reset. That line is spent: it
+    reopens no wait (whose reset, now read as tomorrow's, lies beyond the cap and
+    would park the session) and does not label the timeout usage-limited.
+
+    Ablation: drop the `spent` skip at admission and the session ends stalled +
+    parked on `quota-wait-skipped`; drop it from the timeout path and the verdict
+    is usage-limited."""
+    q = _quota_adapter(tmp_path, monkeypatch)
+
+    def script(call_n):
+        if call_n == 8:
+            _grow(q.transcript, _assistant_line())  # continued after the reset
+            monkeypatch.setattr(
+                generic, "_local_now", lambda: datetime(2026, 10, 25, 19, 25, tzinfo=timezone.utc)
+            )
+
+    result = _drive_quota(q, _quota_spec(tmp_path), script=script)
+    assert result.status == "timeout"  # the resumed deadline: mono 1210 + 210
+    assert result.usage_limited is None
+    assert result.usage_limit_resets is None
+    assert result.quota_wait_s == 120.0
+    assert q.quota_kinds() == ["quota-wait-started", "quota-wait-ended"]
+    assert _lifecycle_events(q.adapter, "quota-wait-skipped") == []
+
+
+def test_spent_wait_line_does_not_park_a_stall(tmp_path, monkeypatch):
+    """The same spent line at stall-grace expiry: the pane goes quiet after the
+    CLI continued (no repaint from mono 1210), and the stall gate does not read
+    the left-over line as a usage limit. The session is not parked or
+    usage-limited and no nudge is withheld for it.
+
+    Ablation: drop the `spent` skip from the stall gate and the session ends
+    stalled + parked + usage-limited."""
+    q = _quota_adapter(tmp_path, monkeypatch, grace=120.0)
+
+    def script(call_n):
+        if call_n < 8:
+            _grow(q.log, "\r⠋".encode())  # the countdown repaints until it continued
+        if call_n == 8:
+            _grow(q.transcript, _assistant_line())
+
+    result = _drive_quota(q, _quota_spec(tmp_path, timeout_s=1000.0), script=script, repaint=False)
+    assert q.quota_kinds() == ["quota-wait-started", "quota-wait-ended"]
+    assert result.usage_limited is None
+    assert not result.parked
+    assert _lifecycle_events(q.adapter, "stall-nudge-withheld") == []
+
+
+def test_fresh_wait_line_after_a_spent_one_opens_a_new_wait(tmp_path, monkeypatch):
+    """A second limit after the CLI continued prints a NEW line (below the spent
+    one, its own reset): that is fresh evidence, and a second wait opens on it.
+
+    Ablation: skip every usage line once a wait has ended, rather than only the
+    spent one, and the second wait never opens."""
+    q = _quota_adapter(tmp_path, monkeypatch)
+    second = "⎿  You've hit your session limit · resets 11:20pm"
+
+    def script(call_n):
+        if call_n == 8:
+            _grow(q.transcript, _assistant_line())  # continued after the reset
+            q.mux.screen = f"{USAGE_SESSION_LINE}\r\n{second}\r\n❯ \r\n"
+        if call_n == 20:
+            _grow(q.transcript, _assistant_line())
+        if call_n == 21:
+            q.finish_spec()
+
+    result = _drive_quota(
+        q,
+        _quota_spec(tmp_path, cap_s=18000.0),  # the 11:20pm reset is ~4 h out
+        events={21: _stop_event("3-1-dev-1", "sess", str(q.transcript))},
+        script=script,
+    )
+    assert result.status == "completed"
+    assert q.quota_kinds() == ["quota-wait-started", "quota-wait-ended"] * 2
+    first, fresh = _lifecycle_events(q.adapter, "quota-wait-started")
+    assert first["evidence"] == q.wait_evidence()
+    pattern = q.adapter.profile.usage_wait_patterns[0]
+    assert fresh["evidence"] == f"pane matched {pattern!r}: {second.strip()}"
+    assert fresh["resets_at"] == "2026-10-25T23:20:00+00:00"
+
+
 # ------------------------------------------ usage-limit reset parse (#610)
 #
 # The matched wait/limit line's `resets …` clause is parsed (`usagereset`) from

From 10c9154514578e879014072bffebcfdd79067c4b Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Sun, 25 Oct 2026 14:01:48 -0700
Subject: [PATCH 8/8] fix(adapters): keep a working session's stall out of the
 usage-limit verdict

A usage-limit line left on screen by a session that recovered with no quota
wait ever admitted labelled a later stall usage-limited when the pane went
quiet past the grace on a silent foreground tool or a still-moving transcript.
The env-fault classifier exempts that label from the token veto, so the run
paused uncharged for a limit long gone. The stall gate now applies the same
activity tests the timeout path does (transcript written within
QUOTA_WAIT_IDLE_S, or an unanswered tool call), shared as `still_working`.
---
 docs/FEATURES.md                  |  2 +-
 docs/adapter-authoring-guide.md   |  9 ++++---
 src/bmad_loop/adapters/generic.py | 42 ++++++++++++++++++-------------
 tests/test_generic_tmux.py        | 26 +++++++++++++++++++
 4 files changed, 56 insertions(+), 23 deletions(-)

diff --git a/docs/FEATURES.md b/docs/FEATURES.md
index 336c9030a..788a7008d 100644
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -162,7 +162,7 @@ bmad-loop drives a BMAD sprint unattended: a deterministic Python loop launches
   - A non-completed session whose log tail matches its profile's `env_fault_patterns` pauses instead of spending a dev attempt.
   - opencode is classified from model-free files only: the server's stdout, plus on OpenCode 2.x the adapter-written `provider-errors.log` (one line per provider-error event). Its 2.x patterns cover the `provider.rate-limit`, `provider.quota` and `provider.transport` error types.
   - A pattern match is overruled when the session's tracked token usage is nonzero; that session is charged like any failure.
-  - A session whose visible pane shows a usage-limit line from its profile's `usage_limit_patterns` or `usage_wait_patterns`, at stall-grace expiry or when the timeout fires on an idle session, pauses with a `usage limit:` reason and is never charged, whatever its token usage; the same line found only in the log tail stays subject to the overrule.
+  - A session whose visible pane shows a usage-limit line from its profile's `usage_limit_patterns` or `usage_wait_patterns`, on an idle session at stall-grace expiry or when the timeout fires, pauses with a `usage limit:` reason and is never charged, whatever its token usage; the same line found only in the log tail stays subject to the overrule.
   - When the usage-limit line names a reset time, the pause reason ends its evidence with `; resets <time>` (ISO-8601 when the time resolves, the raw text otherwise).
 - **Config:** `[environment] probes`, `[environment] probe_timeout_s`, `[verify] env_fault_rc`, `[limits] quota_wait_max_min`; profile keys `env_fault_patterns`, `usage_limit_patterns`, `usage_wait_patterns`
 - **Tested by:** `tests/test_engine.py`, `tests/test_escalation.py`, `tests/test_env_fault_patterns.py`, `tests/test_env_fault.py`, `tests/test_generic_tmux.py`, `tests/test_opencode_http.py`, `tests/test_usagereset.py`
diff --git a/docs/adapter-authoring-guide.md b/docs/adapter-authoring-guide.md
index 75bfcb69c..eeaf0c44d 100644
--- a/docs/adapter-authoring-guide.md
+++ b/docs/adapter-authoring-guide.md
@@ -483,10 +483,11 @@ patterns and both usage lists. A usage match withholds the nudge (even when a ho
 such as `idle_prompt` is set, since an idle CLI behind a limit latches exactly that) and
 ends the session `stalled` + `parked` with `SessionResult.usage_limited` holding the
 matched evidence. **When the session timeout fires**, one capture against both lists sets
-`usage_limited` on the `timeout` result, unless the session is visibly working: a
-transcript written within the last 90 s (as of the last heartbeat) or an unanswered tool
-call means the line is left over from a limit it recovered from, and the timeout is an
-ordinary one. A dead window is never usage-limited.
+`usage_limited` on the `timeout` result. Neither gate takes a usage match from a session
+that is visibly working: a transcript written within the last 90 s (as of the last
+heartbeat) or an unanswered tool call means the line is left over from a limit it
+recovered from, and the stall or timeout is an ordinary one. A dead window is never
+usage-limited.
 
 A `usage_limited` result is classified as an environment fault with no token-usage
 overrule and no tail scan, and pauses with a `usage limit:` reason (see
diff --git a/src/bmad_loop/adapters/generic.py b/src/bmad_loop/adapters/generic.py
index 6054f75c7..4978e0348 100644
--- a/src/bmad_loop/adapters/generic.py
+++ b/src/bmad_loop/adapters/generic.py
@@ -1516,6 +1516,21 @@ def produced_work() -> bool:
                 handle, stop_seen, activity_seen or transcript_work_seen or usage_seen
             )
 
+        def still_working() -> bool:
+            """The quota wait's activity tests (#610), for a usage line seen at
+            stall-grace expiry or at the timeout. A visible line alone is not
+            proof the CLI is still blocked: one that recovered and kept working
+            can leave it on screen. A transcript written inside QUOTA_WAIT_IDLE_S
+            (as of the last heartbeat sample) or an unanswered tool call is a
+            working session, and so is a tool scan that faults. Unknown activity
+            (no transcript named yet, or no sample) keeps the pane's word."""
+            path = transcript_path
+            if not path:
+                return False
+            if idle.idle_s is not None and idle.idle_s < QUOTA_WAIT_IDLE_S:
+                return True
+            return self._quota_wait_tool_open(handle, path)
+
         def stall_exit(
             parked_now: str | None, usage_now: str | None, resets_now: str | None = None
         ) -> SessionResult:
@@ -1623,15 +1638,9 @@ def stall_exit(
                 # failed attempt. A dead window is never usage-limited (the CLI
                 # is gone, though a remain-on-exit pane still captures), so a
                 # match is confirmed alive first; a probe fault reads "not dead".
-                # A visible line alone is not proof the CLI is still blocked:
-                # one that recovered and kept working can leave it on screen.
-                # The quota wait's activity tests apply here too — a transcript
-                # written inside QUOTA_WAIT_IDLE_S (as of the last heartbeat
-                # sample) or an unanswered tool call is a working session, and
-                # its timeout is an ordinary one, charged as before #610 (so is
-                # a tool scan that faults). Unknown activity (no transcript
-                # named yet, or no sample) keeps the pane's word. A line a
-                # quota wait already continued from is no evidence at all.
+                # A working session's timeout (`still_working`) is an ordinary
+                # one, charged as before #610. A line a quota wait already
+                # continued from is no evidence at all.
                 (usage_hit,) = self._pane_evidence(
                     handle, self._usage_pane_patterns, skip=quota.spent
                 )
@@ -1639,13 +1648,7 @@ def stall_exit(
                 if (
                     usage_hit is not None
                     and self._probe_liveness(handle, "timeout") is not False
-                    and not (
-                        transcript_path
-                        and (
-                            (idle.idle_s is not None and idle.idle_s < QUOTA_WAIT_IDLE_S)
-                            or self._quota_wait_tool_open(handle, transcript_path)
-                        )
-                    )
+                    and not still_working()
                 ):
                     usage_now = usage_hit[0]
                     reset = self._usage_reset(handle, usage_hit[1], _local_now())
@@ -2086,7 +2089,10 @@ def stall_exit(
                     # match is recorded as `usage_limited` even when the hook
                     # latch already supplied the parked evidence, since claude's
                     # idle_prompt latches on exactly this kind of idle. A line a
-                    # quota wait already continued from matches nothing.
+                    # quota wait already continued from matches nothing, and
+                    # neither does one on a working session (`still_working`:
+                    # a silent foreground tool past the grace, say), which
+                    # stalls as before #610 rather than pausing uncharged.
                     parked_now = parked_evidence
                     parked_hit, usage_hit = self._pane_evidence(
                         handle,
@@ -2097,7 +2103,7 @@ def stall_exit(
                     if parked_now is None and parked_hit is not None:
                         parked_now = parked_hit[0]
                     usage_now = resets_now = None
-                    if usage_hit is not None:
+                    if usage_hit is not None and not still_working():
                         usage_now = usage_hit[0]
                         reset = self._usage_reset(handle, usage_hit[1], _local_now())
                         resets_now = reset.value if reset is not None else None
diff --git a/tests/test_generic_tmux.py b/tests/test_generic_tmux.py
index 74d3fbd9e..3df98b58e 100644
--- a/tests/test_generic_tmux.py
+++ b/tests/test_generic_tmux.py
@@ -13201,6 +13201,32 @@ def script(call_n):
     assert _lifecycle_events(q.adapter, "stall-nudge-withheld") == []
 
 
+@pytest.mark.parametrize("activity", ["open-tool", "active-transcript"])
+def test_working_session_stall_is_not_usage_limited(tmp_path, monkeypatch, activity):
+    """A limit line left on screen by a session that recovered with no wait
+    ever admitted, and a quiet pane past the grace: a silent foreground tool
+    (an unanswered `Bash` call), or a transcript still being written. The
+    stall gate applies the quota wait's activity tests, as the timeout does:
+    the session is not parked or usage-limited (which would pause the run
+    uncharged for a limit long gone) and no nudge is withheld for it.
+
+    Ablation: drop `still_working()` from the stall gate and both cases end
+    stalled + parked + usage-limited."""
+    q = _quota_adapter(tmp_path, monkeypatch, grace=120.0)
+    if activity == "open-tool":
+        _grow(q.transcript, _tool_use("t1", "Bash", "2026-01-01T00:00:01Z"))
+
+    def script(call_n):
+        if activity == "active-transcript":
+            _grow(q.transcript, _assistant_line())
+
+    result = _drive_quota(q, _quota_spec(tmp_path, timeout_s=1000.0), script=script, repaint=False)
+    assert q.quota_kinds() == []
+    assert result.usage_limited is None
+    assert not result.parked
+    assert _lifecycle_events(q.adapter, "stall-nudge-withheld") == []
+
+
 def test_fresh_wait_line_after_a_spent_one_opens_a_new_wait(tmp_path, monkeypatch):
     """A second limit after the CLI continued prints a NEW line (below the spent
     one, its own reset): that is fresh evidence, and a second wait opens on it.