ph-core 0.2.0__tar.gz → 0.4.0__tar.gz

{ph_core-0.2.0 → ph_core-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ph-core
-Version: 0.2.0
+Version: 0.4.0
 Summary: pH core: the cordis plugin subset, the session log, the LLM vocabulary, and the agent loop.
 Project-URL: Homepage, https://github.com/chastabor/pH
 Project-URL: Repository, https://github.com/chastabor/pH
@@ -153,11 +153,11 @@ phern config --row containment --profile tui # one row's knobs, defaults and wha
 | `containment` | `tier`, `childTier`, `strict` | **unset** — which is not `advisory`: unset means nobody chose, so a tier provider a profile layered is used |
 | `workspace-lifecycle` | `access`, `provision` | `write` |
 | `jobs-local` | `concurrency` (per job kind) | unset |
-| `llm-retry` | `maxAttempts`, `baseDelayMs`, `maxDelayMs` | `3`, `500`, `20000` |
+| `llm-retry` | `maxAttempts`, `baseDelayMs`, `maxDelayMs`, `countAllRetries` | `3`, `500`, `20000`, `false` — only `llm-retry`'s own retries spend its budget; `true` counts every row's, compaction's included |
 | `session-telemetry` | `enabled`, `path` | `enabled: false` in `ph-base` |
 | `subagent-presets` | `presets` | empty — a menu, never a grant: selecting a preset never widens what the parent itself holds |
 | `skills-progressive` | `paths` | **empty on purpose** — scanning a well-known directory would make "install a skill" mean "drop a file somewhere" (I7) |
-| `autonomous` | `maxContinuations`, `maxTurns`, `maxTokens`, `timeoutMs` | `3`, `12`, `80000`, `1800000` |
+| `autonomous` | `maxContinuations`, `maxTurns`, `maxTokens`, `timeoutMs`, `tokenSources` | `3`, `12`, `80000`, `1800000`, `[own]` — add `compaction` and `children` to charge summaries and subagents to `maxTokens` |
 | `subprocess-local` | `scrub`, `keep`, `maxOutputBytes` | `8388608` |
 | `tool-attach` | `maxBytes` | `33554432` |
 

{ph_core-0.2.0 → ph_core-0.4.0}/README.md

@@ -119,11 +119,11 @@ phern config --row containment --profile tui # one row's knobs, defaults and wha
 | `containment` | `tier`, `childTier`, `strict` | **unset** — which is not `advisory`: unset means nobody chose, so a tier provider a profile layered is used |
 | `workspace-lifecycle` | `access`, `provision` | `write` |
 | `jobs-local` | `concurrency` (per job kind) | unset |
-| `llm-retry` | `maxAttempts`, `baseDelayMs`, `maxDelayMs` | `3`, `500`, `20000` |
+| `llm-retry` | `maxAttempts`, `baseDelayMs`, `maxDelayMs`, `countAllRetries` | `3`, `500`, `20000`, `false` — only `llm-retry`'s own retries spend its budget; `true` counts every row's, compaction's included |
 | `session-telemetry` | `enabled`, `path` | `enabled: false` in `ph-base` |
 | `subagent-presets` | `presets` | empty — a menu, never a grant: selecting a preset never widens what the parent itself holds |
 | `skills-progressive` | `paths` | **empty on purpose** — scanning a well-known directory would make "install a skill" mean "drop a file somewhere" (I7) |
-| `autonomous` | `maxContinuations`, `maxTurns`, `maxTokens`, `timeoutMs` | `3`, `12`, `80000`, `1800000` |
+| `autonomous` | `maxContinuations`, `maxTurns`, `maxTokens`, `timeoutMs`, `tokenSources` | `3`, `12`, `80000`, `1800000`, `[own]` — add `compaction` and `children` to charge summaries and subagents to `maxTokens` |
 | `subprocess-local` | `scrub`, `keep`, `maxOutputBytes` | `8388608` |
 | `tool-attach` | `maxBytes` | `33554432` |
 

{ph_core-0.2.0 → ph_core-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ph-core"
-version = "0.2.0"
+version = "0.4.0"
 description = "pH core: the cordis plugin subset, the session log, the LLM vocabulary, and the agent loop."
 readme = "README.md"
 requires-python = ">=3.12"

{ph_core-0.2.0 → ph_core-0.4.0}/src/ph/__init__.py

@@ -6,4 +6,4 @@ and `plans/Implementation_Plan.md` for the work breakdown.
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

{ph_core-0.2.0 → ph_core-0.4.0}/src/ph/agent/inbox.py

@@ -27,8 +27,11 @@ from pydantic import ConfigDict
 from ..json import JsonObject
 from ..llm.types import Message
 from ..session import Session
+from ..session.writers import log_writer
 from ..wire import WireModel
 
+_LOG = log_writer(__name__)
+
 __all__ = ["Inbox", "InboxNotifications", "InboxTarget"]
 
 InboxTarget: TypeAlias = Literal["next-turn", "next-step"]
@@ -163,7 +166,7 @@ class Inbox:
         # The durable event commits BEFORE the live projection mutates, so a
         # synchronous `session/event` observer sees the pre-splice lists and can
         # reconstruct exactly what was removed from the normalized coordinates.
-        self._session.append("agent/inbox/spliced", splice.to_wire())
+        _LOG.append(self._session, "agent/inbox/spliced", splice.to_wire())
         removed = pending[start : start + delete_count]
         pending[start : start + delete_count] = inserted
         if discard_removed:

{ph_core-0.2.0 → ph_core-0.4.0}/src/ph/agent/registry.py

@@ -17,7 +17,7 @@ from dataclasses import dataclass, field
 
 from ..cordis import Context, events, plugin
 from ..keys import AGENT, AGENTS, SESSIONS
-from ..session import Session
+from ..session import Session, session_written
 from .types import (
     AgentDriver,
     AgentHandle,
@@ -178,6 +178,12 @@ class AgentRegistry:
         # `_forget` rides the scope's own teardown, so the announcement and the
         # roster drop happen exactly once whichever way the scope goes.
         await agent.ctx.dispose()
+        # The teardown just appended to this agent's log — its workspace records
+        # `workspace/disposed` as it lets go — so written here, while the
+        # persistence row is still mounted, rather than whenever the mount
+        # unwinds. A mount's own unwind is `write_on_unwind`'s (F2).
+        if agent.session is not None:
+            await session_written(self.ctx, agent.session)
 
 
 @plugin("agent", inject=[SESSIONS])

{ph_core-0.2.0 → ph_core-0.4.0}/src/ph/agent/types.py

@@ -12,6 +12,7 @@ a listener's signature *is* the contract: the limits and permissions plugins
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Literal, Protocol, TypeAlias
 
@@ -170,6 +171,13 @@ class RequestProposal:
     """`agent/request`: the call config the loop proposes for one request."""
 
     agent: AgentHandle
+    session: Session
+    """Not optional here, for `PreStepRequest.session`'s reason (L5).
+
+    `input-offload` is the listener that had reached through the handle, and it
+    paid the same price `llm-retry` did: a `None` its only producer cannot
+    create, guarded by returning early — so the feature turned itself off rather
+    than failing."""
     turn: int
     step: int
     config: LlmCallConfig
@@ -180,10 +188,37 @@ class RequestFailure:
     """`agent/request-error`: a request that ended in `error` or `aborted`."""
 
     agent: AgentHandle
+    session: Session
+    """Not optional here, for `PreStepRequest.session`'s reason (L5).
+
+    Reaching through the handle instead made `llm-retry` guard a `None` its only
+    producer cannot create, and that guard does not fail loudly: it logs at
+    debug and declines the retry, so a route that had retries configured quietly
+    had none."""
     turn: int
     step: int
     provider: str
     failure: LlmFailure
+    retries_by: Mapping[str, int]
+    """How many times the loop has already retried this step, by the row that asked (G13).
+
+    Keyed by the plugin whose listener granted each retry, as
+    `Context.waterfall_attributed` reports it — `""` for a listener outside any
+    plugin. Counted by the driver, because every retry passes through it.
+    Handed to the policy rather than re-derived there, so a row budgets against
+    its own retries (`retries_by["llm-retry"]`) or against all of them
+    (`retries`) by choosing a number, not by folding a log only some rows write.
+
+    **Per step, per agent, by construction**: the count is a local in the
+    driver's retry loop, so two subagents at the same coordinates cannot share
+    it (I4) — the bug a count held on the listener had. Nothing is lost on a
+    resume either, because a resumed session starts a new turn and never
+    re-enters the step it was retrying."""
+
+    @property
+    def retries(self) -> int:
+        """Every retry this step has had, whichever row asked."""
+        return sum(self.retries_by.values())
 
 
 @dataclass(frozen=True, slots=True)
@@ -192,6 +227,9 @@ class RequestErrorAction:
 
     kind: Literal["retry"]
     delay_ms: int = 0
+    """How long the loop waits before the retry. The loop sleeps it, once the
+    waterfall has settled — never the row — so a listener that refuses the retry
+    costs no wait."""
 
 
 @dataclass(frozen=True, slots=True)

{ph_core-0.2.0 → ph_core-0.4.0}/src/ph/agent_loop/driver.py

@@ -41,7 +41,8 @@ seam unless something shadowed it for this agent alone.
 from __future__ import annotations
 
 import logging
-from collections.abc import Sequence
+from collections import Counter
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -64,7 +65,7 @@ from ..cordis import Context, settled, settled_or_none
 from ..json import as_int
 from ..keys import LLM, SYSTEM_PROMPT
 from ..llm.adapter import LlmError
-from ..llm.assembler import BlockAssembler
+from ..llm.assembler import BlockAssembler, named_call
 from ..llm.types import (
     ContentBlock,
     FinishReason,
@@ -72,7 +73,6 @@ from ..llm.types import (
     LlmCallConfig,
     LlmFailure,
     Message,
-    PluginSource,
     TokenUsage,
     ToolCallBlock,
     create_assistant_message,
@@ -80,15 +80,13 @@ from ..llm.types import (
 )
 from ..session import Session, SurfaceIntent
 from ..session.request_header import EpochHeader, RequestContext, canonical_header, header_equals
-from ..system_prompt.assembly import (
-    PromptAssembly,
-    join_context_sections,
-    render_context_sections,
-    render_prompt,
-)
+from ..session.writers import log_writer
+from ..system_prompt.assembly import PromptAssembly, context_message, render_prompt
 from ..tools.batch import execute_tool_calls
 from ..tools.errors import error_info
 
+_LOG = log_writer(__name__)
+
 __all__ = ["AgentCanceled", "ReactLoopAgent"]
 
 log = logging.getLogger("ph.agent_loop")
@@ -149,7 +147,6 @@ class ReactLoopAgent:
         self.max_parallel_tool_calls = max_parallel_tool_calls
         self._phase = _Phase(turn=_last_turn_of(session))
         self._request_header_logged = False
-        self._context_snapshot: str | None = None
         self._idle = anyio.Event()
         self._idle.set()
         self.inbox = Inbox(
@@ -276,11 +273,21 @@ class ReactLoopAgent:
 
     async def _pre_step(self, target: InboxTarget, turn: int, step: int) -> _PreparedStep:
         self._throw_if_canceled()
-        claimed = self.inbox.claim(target, turn)
+        # **Assembled before the batch is claimed** (C4). `claim` is durable —
+        # it appends `agent/inbox/spliced`, which is what takes the messages out
+        # of the inbox for good — and `assemble` is an await that a person's
+        # interrupt can land in. Claimed first, a cancel there consumed the
+        # prompt and ran nothing: the typed line was gone from the inbox and
+        # never reached a model call. Nothing here needs the batch, so the
+        # ordering costs nothing and the claim now happens on the far side of
+        # the last cancel check before the step is proposed.
         assembly = await self.ctx.require(SYSTEM_PROMPT).assemble(self.ctx, agent=self)
         self._throw_if_canceled()
-        context_message = self._project_context(assembly)
-        messages = (*claimed, context_message) if context_message is not None else tuple(claimed)
+        claimed = self.inbox.claim(target, turn)
+        # Only when the conversation the model is shown lacks it (C12) — see
+        # `context_message`.
+        context = context_message(assembly, self.session.derive_messages())
+        messages = (*claimed, context) if context is not None else tuple(claimed)
 
         async def inner(request: PreStepRequest) -> PreStepDecision:
             return PreStepDecision(kind="enter", messages=request.messages)
@@ -295,34 +302,22 @@ class ReactLoopAgent:
             return _PreparedStep(kind="reject")
         return _PreparedStep(kind="enter", messages=decision.messages, assembly=assembly)
 
-    def _project_context(self, assembly: PromptAssembly) -> Message | None:
-        """Materialize `context()` providers, but only when the text changed.
-
-        This is the whole reason `context()` exists separately from `section`:
-        re-sending unchanged context on every step would invalidate the cached
-        prefix each turn (A12).
-        """
-        sections = render_context_sections(assembly)
-        if not sections:
-            return None
-        text = join_context_sections(sections)
-        if text == self._context_snapshot:
-            return None
-        self._context_snapshot = text
-        return create_user_message(
-            content=[{"type": "text", "text": text}],
-            source=PluginSource(
-                plugin="ph.system-prompt", form="snapshot", sections=list(sections)
-            ),
-        )
-
     async def _turn(self) -> bool:
         phase = self._phase
         self._throw_if_canceled()
         turn = phase.turn + 1
-        self.session.append("turn/start", {"turn": turn})
+        _LOG.append(self.session, "turn/start", {"turn": turn})
         phase.turn = turn
         turn_ends: TurnEndReason | None = None
+        capped = False
+        """Whether any step in this turn stopped at `max_tokens`.
+
+        Kept beside `turn_ends` rather than inside it, because the two answer
+        different questions: what ends the turn, and what the person should be
+        told about it. Folding the second into the first made a `max-tokens` step
+        *end the turn* even where the loop had more to do — see where it is read
+        below.
+        """
         target: InboxTarget = "next-turn"
         try:
             while True:
@@ -341,21 +336,26 @@ class ReactLoopAgent:
                     turn_ends = TurnEndReason(kind="completed")
                     return False
                 self._throw_if_canceled()
-                self.session.append("step/start", {"turn": turn, "step": step})
+                _LOG.append(self.session, "step/start", {"turn": turn, "step": step})
                 phase.step = step
                 try:
                     for message in decision.messages:
-                        self.session.append(
-                            "user/message", message.to_wire(), SurfaceIntent("append")
+                        _LOG.append(
+                            self.session, "user/message", message.to_wire(), SurfaceIntent("append")
                         )
                     assert decision.assembly is not None
                     step_end = await self._step(decision.assembly)
-                    # max-tokens stays sticky: a later completed step must not
-                    # downgrade the turn outcome.
-                    if turn_ends is None or turn_ends.kind != "max-tokens":
-                        turn_ends = step_end
+                    # **The outcome is sticky; the stopping is not.** A step that
+                    # hit `max_tokens` must still be reported as such at the end
+                    # of the turn, however the turn actually finishes — but a
+                    # `None` here means "tools ran, there is more to do", and
+                    # holding the earlier reason for it ended the turn with a
+                    # `tool/result` the model never saw. The two were one
+                    # variable, so the sticky answer was also the deciding one.
+                    capped = capped or (step_end is not None and step_end.kind == "max-tokens")
+                    turn_ends = step_end
                 finally:
-                    self.session.append("step/end", {"turn": turn, "step": step})
+                    _LOG.append(self.session, "step/end", {"turn": turn, "step": step})
                 self._throw_if_canceled()
                 if turn_ends is not None and not self.inbox.next_step:
                     await self.ctx.serial("agent/turn-stopping", self, turn)
@@ -383,9 +383,10 @@ class ReactLoopAgent:
             self._report(error)
             raise
         finally:
-            self.session.append(
+            _LOG.append(
+                self.session,
                 "turn/end",
-                {"turn": turn, "reason": (turn_ends or TurnEndReason(kind="completed")).to_wire()},
+                {"turn": turn, "reason": _turn_reason(turn_ends, capped).to_wire()},
             )
         if not self.inbox.has_pending:
             return False
@@ -398,6 +399,17 @@ class ReactLoopAgent:
         self._throw_if_canceled()
         system = render_prompt(assembly)
 
+        # **Which attempt this is, because a retried step keeps its coordinates**
+        # (G12). That is deliberate — `llm/retry` is legible in the log because
+        # of it — but it leaves `(turn, step)` naming a *step* where a model
+        # *call* is what needs the name. Two attempts minted the same tool-call
+        # ids and `recorded_steps` had to infer the boundary between them.
+        #
+        # **Counted here because this is the only place every retry passes**,
+        # by the row that asked (G13): the attempt is the total, and a policy's
+        # budget is its own share or the total as it chooses.
+        retries: Counter[str] = Counter()
+        attempt = 0
         while True:
             request = await self._build_request(turn, step, assembly, system)
             assembler = BlockAssembler()
@@ -407,13 +419,28 @@ class ReactLoopAgent:
                 self._throw_if_canceled()
                 async for chunk in stream:
                     self._throw_if_canceled()
+                    # **Named before it is logged** (G11): a tool call the
+                    # provider did not name gets its id here, so the raw record
+                    # and the assembled message agree about it. This is the only
+                    # consumer that pairs a call to a result, and the only one
+                    # holding the coordinates the id is built from.
+                    chunk = named_call(chunk, turn, step, attempt)
                     # Raw chunks are logged before assembly, so the log carries
                     # token-level replay fidelity even for a stream that later
                     # fails.
                     chunk_seqs.append(
-                        self.session.append(
+                        _LOG.append(
+                            self.session,
                             "assistant/chunk",
-                            {"turn": turn, "step": step, "chunk": chunk.to_wire()},
+                            {
+                                "turn": turn,
+                                "step": step,
+                                # The call's own coordinate, so `recorded_steps`
+                                # reads the boundary between two attempts rather
+                                # than inferring it (G12).
+                                "attempt": attempt,
+                                "chunk": chunk.to_wire(),
+                            },
                         ).seq
                     )
                     assembler.push(chunk)
@@ -431,12 +458,31 @@ class ReactLoopAgent:
 
             finish = assembler.finish
             if finish.kind in ("error", "aborted"):
-                action = await self._request_error(turn, step, request, finish)
+                action, by = await self._request_error(turn, step, retries, request, finish)
                 if action is None or action.kind != "retry":
                     failure = finish.failure or LlmFailure(
                         message="model request failed", code="UNKNOWN"
                     )
                     raise LlmError(failure.message, failure.code, failure)
+                retries[by] += 1
+                attempt = retries.total()
+                # The loop's own record of the call it is about to make again,
+                # beside `step/start` for the first one (P1): the log's answer
+                # to "how many model calls", whichever row asked for the retry.
+                # `llm/retry` is `llm-retry`'s account of itself and a compaction
+                # retry writes none, so a ceiling counting those undercounts.
+                _LOG.append(
+                    self.session,
+                    "step/retry",
+                    {"turn": turn, "step": step, "attempt": attempt, "by": by},
+                )
+                # **The wait is the loop's**, after the waterfall has settled: a
+                # row that slept inside it answered only after a later veto
+                # could no longer save the time, and a gate had to run *ahead*
+                # of it to refuse at all (P1 review).
+                if action.delay_ms > 0:
+                    await anyio.sleep(action.delay_ms / 1000)
+                    self._throw_if_canceled()
                 continue
 
             blocks = assembler.blocks()
@@ -475,21 +521,38 @@ class ReactLoopAgent:
         return TurnEndReason(kind="completed") if outcome.concluded else None
 
     async def _request_error(
-        self, turn: int, step: int, request: GenerateOptions, finish: FinishReason
-    ) -> RequestErrorAction | None:
+        self,
+        turn: int,
+        step: int,
+        retries: Mapping[str, int],
+        request: GenerateOptions,
+        finish: FinishReason,
+    ) -> tuple[RequestErrorAction | None, str]:
+        """The chain's answer, and the row whose listener gave it.
+
+        Attributed by cordis rather than claimed on the action (G13): the retry
+        is counted under the plugin that granted it, which a row could otherwise
+        misname and which cordis already knows.
+        """
+
         async def inner(request_failure: RequestFailure) -> RequestErrorAction | None:
             return None
 
         failure = RequestFailure(
             agent=self,
+            session=self.session,
             turn=turn,
             step=step,
             provider=request.provider,
             failure=finish.failure or LlmFailure(message="model request failed", code="UNKNOWN"),
+            # A copy: the payload is a snapshot, and the loop goes on counting.
+            retries_by=dict(retries),
+        )
+        action, by = await self.ctx.waterfall_attributed(
+            "agent/request-error", failure, inner=inner
         )
-        action = await self.ctx.waterfall("agent/request-error", failure, inner=inner)
         self._throw_if_canceled()
-        return settled_or_none("agent/request-error", action, RequestErrorAction)
+        return settled_or_none("agent/request-error", action, RequestErrorAction), by
 
     def _append_assistant_message(
         self,
@@ -510,7 +573,9 @@ class ReactLoopAgent:
             data["usage"] = usage.to_wire()
         if interrupted:
             data["interrupted"] = True
-        self.session.append("assistant/message", data, SurfaceIntent("append", tuple(chunk_seqs)))
+        _LOG.append(
+            self.session, "assistant/message", data, SurfaceIntent("append", tuple(chunk_seqs))
+        )
 
     async def _build_request(
         self, turn: int, step: int, assembly: PromptAssembly, system: str
@@ -531,7 +596,9 @@ class ReactLoopAgent:
         async def inner(proposal: RequestProposal) -> LlmCallConfig:
             return proposal.config
 
-        proposal = RequestProposal(agent=self, turn=turn, step=step, config=seed)
+        proposal = RequestProposal(
+            agent=self, session=self.session, turn=turn, step=step, config=seed
+        )
         answered = await self.ctx.waterfall("agent/request", proposal, inner=inner)
         self._throw_if_canceled()
         proposed = settled("agent/request", answered, LlmCallConfig)
@@ -546,20 +613,21 @@ class ReactLoopAgent:
         )
         baseline = session.request_header()
         if not self._request_header_logged:
-            session.append(
+            _LOG.append(
+                session,
                 "request/header",
                 {"header": header.to_wire(), "reason": "initial" if baseline is None else "resume"},
             )
             self._request_header_logged = True
         elif baseline is None or not header_equals(baseline, header):
-            session.append("request/header", {"header": header.to_wire(), "reason": "change"})
+            _LOG.append(session, "request/header", {"header": header.to_wire(), "reason": "change"})
 
         resolved = self.ctx.require(LLM).resolve_model(proposed.provider, proposed.model)
         request_context = RequestContext(
             provider=proposed.provider, model=proposed.model, context_window=resolved.context_window
         )
         if session.request_context() != request_context:
-            session.append("request/context", request_context.to_wire())
+            _LOG.append(session, "request/context", request_context.to_wire())
         self._throw_if_canceled()
 
         return GenerateOptions(
@@ -609,6 +677,45 @@ def _error_chain(error: BaseException) -> str:
     return ": ".join(parts)
 
 
+def _turn_reason(ends: TurnEndReason | None, capped: bool) -> TurnEndReason:
+    """What `turn/end` records, given how the loop left and what it passed through.
+
+    **A cap is not erased by finishing.** A step that hit `max_tokens` cut the
+    model off, and the turn may then have carried on — a steer, a tool call,
+    another step — and ended tidily. Reporting that as `completed` tells the
+    person their answer is whole when part of it was dropped, so `max-tokens`
+    outranks the two endings that mean "nothing went wrong".
+
+    It does not outrank the three that say more: `aborted`, `blocked` and
+    `error` each name something the reader has to act on, and a cap somewhere in
+    the turn is the smaller fact beside them.
+
+    **`None` means an exception left the body, so it is `aborted`** (C9). Every
+    normal exit from `_turn` assigns `ends` first — both `break`s are guarded by
+    `turn_ends is not None` and both `return` paths set it — so a `None` arriving
+    here cannot be a turn that finished. It used to read as `completed`, and each
+    `except` branch in `_turn` existed to write over that default before the
+    `finally` could believe it.
+
+    Deriving it here instead of catching it there is what makes the coverage
+    total. A branch for `anyio.get_cancelled_exc_class()` still misses the
+    `BaseExceptionGroup` an anyio task group raises around one, and
+    `KeyboardInterrupt`, and `SystemExit` — each of which would have recorded a
+    turn that finished nothing as *completed*, so the resume path saw no open
+    turn to repair and a reader was told a story the run did not have.
+
+    `kind="user"` is the honest cause for that case: something outside the turn
+    decided, and the loop cannot see what. The harness's own cancellations arrive
+    as `AgentCanceled`/`Canceled`, are caught in `_turn`, and carry their real
+    cause.
+    """
+    if ends is None:
+        return TurnEndReason(kind="aborted", reason=AgentCancelCause(kind="user"))
+    if ends.kind == "completed":
+        return TurnEndReason(kind="max-tokens" if capped else "completed")
+    return ends
+
+
 def _as_failure(error: Exception) -> LlmFailure:
     """A raised error as a turn's `reason.error`, keeping its code if it has one.