by-framework 0.2.2.dev11__py3-none-any.whl → 0.2.2.dev13__py3-none-any.whl

by_framework/client/client.py

@@ -14,6 +14,7 @@ from typing import (TYPE_CHECKING, Any, AsyncIterator, Dict, List, Optional, Pro
 
 from by_framework.common.constants import (
     CANCEL_MESSAGE_ID_PREFIX,
+    CLIENT_SOURCE_AGENT_TYPE,
     EXECUTION_ID_PREFIX,
     MESSAGE_ID_PREFIX,
     RedisKeys,
@@ -864,7 +865,7 @@ class GatewayClient:
                             trace_id=trace_id,
                             target_agent_type=params["target_agent_type"],
                             parent_message_id=params["parent_message_id"] or "",
-                            source_agent_type="client",
+                            source_agent_type=CLIENT_SOURCE_AGENT_TYPE,
                             route_policy=route_policy,
                             route_status=availability.status,
                             stream_name=availability.stream_name or "",
@@ -968,7 +969,7 @@ class GatewayClient:
                         "session_id": params["session_id"],
                         "trace_id": trace_id,
                         "parent_message_id": params["parent_message_id"] or "",
-                        "source_agent_type": "client",
+                        "source_agent_type": CLIENT_SOURCE_AGENT_TYPE,
                         "target_agent_type": params["target_agent_type"],
                         "stream_name": route.stream_name,
                         "status": "QUEUED",
@@ -1117,7 +1118,7 @@ class GatewayClient:
                     message_id=message_id,
                     parent_message_id=parent_message_id,
                     worker_id=target_worker_id,
-                    source_agent_type="client",
+                    source_agent_type=CLIENT_SOURCE_AGENT_TYPE,
                     target_agent_type=target_agent_type,
                     route_policy=route_policy,
                     route_status=route_status,

by_framework/common/constants.py

@@ -297,6 +297,100 @@ class RedisKeys:
             v2_suffix=f"task_group:{{{group_id}}}:results",
         )
 
+    @classmethod
+    def wait_index(cls, shard: int) -> str:
+        """ZSET index of suspended callers waiting for a sub-task reply.
+
+        member = encoded wait-index member (see core/wait_index.py),
+        score = deadline in epoch milliseconds. Sharded so sweepers can
+        claim disjoint slices without a global lock; the shard is derived
+        from session_id (see wait_index_shard()).
+
+        Cross-entity index (spans every session), so deliberately left
+        untagged relative to the per-session keys it points at — same rule
+        as trace_index_session/admin_workers.
+        """
+        return cls._versioned(
+            v1_key=f"byai_gateway:wait:index:{shard}",
+            v2_suffix=f"wait:index:{shard}",
+        )
+
+    @classmethod
+    def wait_sweep_lock(cls, shard: int) -> str:
+        """Short-lived claim on one wait_index() shard, held while sweeping it.
+
+        Ownership is advisory: it only keeps two sweepers from doing the same
+        triage at the same moment. Losing it (expiry, a partitioned worker)
+        cannot corrupt anything, because every action a sweep takes is
+        idempotent — a duplicate synthesized reply is caught by the same
+        wait-index gate that catches a duplicate real one. That is why the
+        shards need no leader election: a dead worker's claim simply expires
+        and another worker picks the shard up on its next cycle.
+
+        Cross-entity like the shard it guards, so deliberately untagged.
+        """
+        return cls._versioned(
+            v1_key=f"byai_gateway:wait:sweep_lock:{shard}",
+            v2_suffix=f"wait:sweep_lock:{shard}",
+        )
+
+    @classmethod
+    def wait_consumed(cls, session_id: str, member_digest: str) -> str:
+        """Short-lived marker: "this wait-index entry was already resolved".
+
+        Written by the idempotency gate right after it wins the ZREM for a
+        member, and read when a later ZREM for the same member returns 0.
+        It is the *only* thing that distinguishes the two meanings of that
+        0 — "someone already consumed this wait" (drop the duplicate) from
+        "this wait was never registered" (a pre-upgrade or expired entry,
+        which must be let through). Without it, every rolling upgrade would
+        silently drop in-flight replies.
+
+        Per-session entity, so hash-tagged with the session in v2.
+        """
+        return cls._versioned(
+            v1_key=f"byai_gateway:wait:consumed:{session_id}:{member_digest}",
+            v2_suffix=f"wait:consumed:{{{session_id}}}:{member_digest}",
+        )
+
+    @classmethod
+    def wait_renew_origin(cls, session_id: str, member_digest: str) -> str:
+        """The deadline a wait's renewal budget is measured from.
+
+        Written once (SET NX) by the first sweep that finds the entry due, so
+        it holds the wait's *original* deadline even after renewals have
+        overwritten the ZSET score. Without it a renewal budget cannot exist
+        at all: every sweep would re-measure from the score it just pushed
+        out, and a callee whose worker is alive but making no progress would
+        be renewed forever.
+
+        Sweeper-private: nothing on the reply path reads or writes it, so it
+        is deliberately NOT part of the wait-index member (which must stay
+        rebuildable from a reply alone — see core/wait_index.py). Expiring is
+        safe by design: losing it only restarts the budget from the current
+        deadline, so the TTL is sized well above any plausible budget.
+
+        Per-session entity, so hash-tagged with the session in v2.
+        """
+        return cls._versioned(
+            v1_key=f"byai_gateway:wait:renew_origin:{session_id}:{member_digest}",
+            v2_suffix=f"wait:renew_origin:{{{session_id}}}:{member_digest}",
+        )
+
+    @classmethod
+    def harness_state(cls, execution_id: str) -> str:
+        """Serialized in-flight native-agent-harness loop state.
+
+        Keyed purely by execution_id — the same identity the registry
+        already reattaches on RESUME — so any worker instance that picks up
+        the eventual ResumeCommand can rehydrate the loop, not only the one
+        that started it.
+        """
+        return cls._versioned(
+            v1_key=f"byai_gateway:harness_state:{execution_id}",
+            v2_suffix=f"harness_state:{{{execution_id}}}",
+        )
+
     # --- Registry ---
     @classmethod
     def known_workers(cls) -> str:
@@ -517,8 +611,32 @@ class RedisKeys:
 MESSAGE_ID_PREFIX = "msg-"
 EXECUTION_ID_PREFIX = "exec-"
 TASK_GROUP_ID_PREFIX = "tg-"
+# A single call_agent (non-group) dispatch stores its result in the same
+# task_group_results Hash a real group uses, under a group id derived from
+# the sub-task's own message_id — i.e. a group of size 1. Keeps one result
+# storage/recovery path instead of two.
+TASK_GROUP_SINGLE_ID_PREFIX = "tg-single-"
 CANCEL_MESSAGE_ID_PREFIX = "msg-cancel-"
 
+# Sentinel GatewayClient writes as an execution record's source_agent_type for
+# a dispatch it made itself (client/client.py's initialize_execution and
+# record_failed_route_decision). It is NOT an agent type: nothing declares it,
+# so nothing consumes RedisKeys.ctrl_stream(CLIENT_SOURCE_AGENT_TYPE).
+#
+# Load-bearing wherever a resumed execution recovers its caller from its own
+# record instead of from the resume header (GatewayWorker._resolve_reply_command
+# / GatewayProcessor._resolve_reply_header): a root execution's record carries
+# this, and treating it as a caller both posts the result to a stream no one
+# reads and suppresses the end-of-stream event the session data plane owes the
+# user — the visible half of the bug being prevented.
+CLIENT_SOURCE_AGENT_TYPE = "client"
+
+
+def single_call_task_group_id(child_message_id: str) -> str:
+    """Group id under which a single (non-group) call_agent result is stored."""
+    return f"{TASK_GROUP_SINGLE_ID_PREFIX}{child_message_id}"
+
+
 # --- Redis Hash Field Prefixes ---
 # Field prefixes in Session Registry Hash
 EXEC_FIELD_PREFIX = "exec:"
@@ -529,6 +647,10 @@ MSG_MAP_PREFIX = "msg_map:"
 TASK_GROUP_FIELD_TOTAL = "total"
 TASK_GROUP_FIELD_COMPLETED = "completed"
 TASK_GROUP_FIELD_SOURCE_AGENT = "source_agent_type"
+# Set once dispatch fails partway through a batch; any reply that arrives
+# for an aborted group is discarded instead of resuming the (already
+# terminated) caller execution.
+TASK_GROUP_FIELD_ABORTED = "aborted"
 
 
 # --- Timing and Sleep Constants ---
@@ -538,12 +660,133 @@ CONTROL_LOOP_SLEEP_SECONDS = 0.01
 WAIT_FOR_TASKS_TIMEOUT_SECONDS = 5.0
 # Task group Key TTL (seconds), default 1 day
 TASK_GROUP_TTL_SECONDS = 86400
+# Native agent harness loop-state Key TTL (seconds), default 1 day
+HARNESS_STATE_TTL_SECONDS = 86400
 # First retry wait time (seconds)
 FIRST_RETRY_WAIT_SECONDS = 1.0
 # Maximum retry count
 MAX_RETRY_COUNT = 3
 
 
+# --- Suspended-caller liveness (wait index) ---
+# Number of RedisKeys.wait_index() shards. Fixed: changing it re-maps every
+# session to a different shard, so in-flight entries would be swept by no
+# one. Treat as a cross-SDK protocol constant, not a tunable.
+WAIT_INDEX_SHARDS = 16
+# Default deadline for a call_agent(wait_for_reply=True) reply (1 hour).
+# Machine waiting on machine.
+DEFAULT_REPLY_TIMEOUT_MS = 3_600_000
+# Default deadline for an ask_user reply. Machine waiting on a human, so it
+# is deliberately decoupled from DEFAULT_REPLY_TIMEOUT_MS and aligned with
+# the session TTL (which is in seconds) instead.
+DEFAULT_ASK_USER_TIMEOUT_MS = RedisKeys.DEFAULT_SESSION_TTL * 1000
+# How often a worker's sweeper scans the shards it owns (seconds).
+WAIT_SWEEP_INTERVAL_SECONDS = 30
+# TTL of a RedisKeys.wait_sweep_lock() claim. Must comfortably exceed one
+# shard's sweep so the owner doesn't lose the shard mid-pass, and stay short
+# enough that a crashed sweeper's shards are picked up again quickly.
+WAIT_SWEEP_LOCK_TTL_SECONDS = 60
+# Most due entries one sweep resolves per shard per cycle. Bounds the work
+# (and the Redis traffic) of a single pass after an outage leaves a large
+# backlog; the remainder is simply picked up next cycle, since entries stay
+# in the index until a reply clears them.
+WAIT_SWEEP_BATCH_LIMIT = 200
+# Fixed extension applied when a sweep finds the callee still making
+# progress. Deliberately a constant rather than the original timeout: the
+# wait-index member must stay reconstructible from a reply alone, so it
+# cannot carry the caller's original timeout.
+WAIT_RENEW_INCREMENT_MS = 300_000
+# Hard ceiling on renewals, as a multiple of the caller's own timeout: a wait
+# may be renewed until `registered_at + N * timeout`, after which the callee
+# is declared CHILD_TIMEOUT even though its worker is still alive.
+#
+# Without a ceiling the "worker lease alive -> renew" rule is unconditional,
+# so a callee that is running but making no progress (a hung LLM call, a
+# deadlock) suspends its caller forever — the one failure mode the deadline
+# was supposed to bound. N is deliberately expressed against the caller's
+# timeout rather than a renewal count, so a caller that asked for 10 minutes
+# is not held to the same absolute budget as one that asked for four hours,
+# and so retuning WAIT_RENEW_INCREMENT_MS cannot silently change the bound.
+#
+# Why 3: N must exceed 1 (N == 1 is "never renew", which kills every callee
+# that is merely slow); N == 2 leaves a single extra window, so one
+# under-estimated timeout is enough to kill healthy work; N == 3 means the
+# caller's own estimate has to be off by 200% before that happens, while
+# still bounding the default case at 3 hours — two orders of magnitude below
+# DEFAULT_SESSION_TTL, which matters because once the session data expires
+# there is no execution record left to compensate against and the wait is
+# simply dropped. Override per deployment via
+# BY_FRAMEWORK_WAIT_RENEW_MAX_MULTIPLE.
+WAIT_RENEW_MAX_MULTIPLE = 3
+# TTL of RedisKeys.wait_renew_origin(). Must comfortably exceed the largest
+# budget in use (N * timeout), or the budget silently restarts mid-wait.
+WAIT_RENEW_ORIGIN_TTL_SECONDS = TASK_GROUP_TTL_SECONDS
+# How long RedisKeys.wait_consumed() remembers that a wait was already
+# resolved, i.e. how far apart two copies of the same reply may be and still
+# be recognized as duplicates.
+#
+# Sized off DEFAULT_SESSION_TTL, which is the lifetime of the session
+# registry — and the session registry is what keeps a *wait entry* relevant.
+# A marker that expires while entries of that session are still live leaves
+# two holes, and the second is the dangerous one:
+#
+#   1. A repeated ask_user answer (a human may take days; the ask_user
+#      deadline is DEFAULT_SESSION_TTL itself) is no longer recognized as a
+#      duplicate and wakes the caller a second time.
+#   2. Worse: a stale duplicate sub-agent reply, having lost the marker that
+#      would stop it at its own candidate, falls through to the ask_user
+#      candidate for the same caller and claims a wait that is still live —
+#      after which the real answer is dropped as "already consumed".
+#
+# Both close once the marker outlives every wait it may have to arbitrate,
+# i.e. the session TTL. Erring long costs a handful of idle 1-byte keys with
+# the same lifetime as the session registry they belong to; erring short
+# costs a lost user answer.
+WAIT_CONSUMED_TTL_SECONDS = RedisKeys.DEFAULT_SESSION_TTL
+# How often a sweeper prunes entries that are provably beyond use (see
+# WAIT_PRUNE_AFTER_SECONDS). Deliberately far coarser than
+# WAIT_SWEEP_INTERVAL_SECONDS: this is garbage collection on a multi-day
+# horizon, and it is the only work a sweeper does when compensation is off.
+WAIT_PRUNE_INTERVAL_SECONDS = 3600
+# How far in the past a wait entry's score must lie before pruning it.
+#
+# Every writer of an entry sets its score to its own `now` plus a
+# non-negative offset (registration adds the caller's timeout, a renewal adds
+# WAIT_RENEW_INCREMENT_MS), and only ever does so while the caller's
+# execution record exists. So `now - score > this` proves the entry was last
+# touched more than a session TTL ago, hence that the session registry the
+# sweep would interrogate has expired and no triage is possible any more:
+# the entry can only ever produce "caller missing". Pruning it is therefore
+# not a decision, which is why it needs no opt-in.
+#
+# The margin over DEFAULT_SESSION_TTL is what makes that strict rather than
+# coincident: DEFAULT_ASK_USER_TIMEOUT_MS *equals* the session TTL, so a
+# threshold trimmed to the session TTL exactly would land on the boundary of
+# a live ask_user wait and lose to any clock skew between the worker that
+# registered the entry and the one sweeping it. A day is far beyond plausible
+# skew, and being late costs one ZSET member per unresolved call for one
+# extra day — the asymmetry says err long.
+WAIT_PRUNE_AFTER_SECONDS = RedisKeys.DEFAULT_SESSION_TTL + 86400
+
+
+class LivenessErrorCode:
+    """error_code values carried by synthesized/recovered resume replies.
+
+    Cross-SDK wire contract — Python/TS/Java must emit the same strings;
+    callers match on them. Append only, never rename.
+    """
+
+    # The callee's worker lease expired while its execution was non-terminal.
+    CHILD_WORKER_LOST = "CHILD_WORKER_LOST"
+    # The callee was alive but produced no reply before the deadline.
+    CHILD_TIMEOUT = "CHILD_TIMEOUT"
+    # The dispatch was never picked up by any worker.
+    CHILD_NEVER_STARTED = "CHILD_NEVER_STARTED"
+    # The callee finished and its result was persisted, but the reply
+    # message was lost; the result was recovered from storage.
+    REPLY_LOST_RECOVERED = "REPLY_LOST_RECOVERED"
+
+
 # --- Filesystem Constants ---
 DEFAULT_WORKSPACE_DIR = "/workspace"
 

by_framework/core/protocol/event_type.py

@@ -21,6 +21,10 @@ class EventType(str, Enum):
         TASK_CREATE: Task creation event
         STEP_COMPLETE: Step completion event
         TASK_STOP: Task stop event
+        ORPHANED_REPLY: A reply that arrived for an already-resolved wait and
+            was therefore dropped by the idempotency gate. Diagnostic only —
+            the sub-agent did real work whose result nobody will consume, so
+            it must not vanish silently.
     """
 
     ANSWER_DELTA = "answerDelta"
@@ -32,3 +36,4 @@ class EventType(str, Enum):
     TASK_CREATE = "taskCreate"
     STEP_COMPLETE = "stepComplete"
     TASK_STOP = "taskStop"
+    ORPHANED_REPLY = "orphanedReply"

by_framework/core/registry.py

@@ -239,6 +239,33 @@ async def check_worker_online(
     return is_legacy or last_seen > 0
 
 
+async def acquire_scoped_lock(
+    redis: Redis,
+    key: str,
+    token: str,
+    ttl_seconds: int,
+) -> bool:
+    """Claim `key` for `token` if nobody holds it (Redlock acquire half).
+
+    The stored value must stay a cjson-decodable object carrying a "token"
+    field: `_REFRESH_LOCK_SCRIPT` / `_RELEASE_LOCK_SCRIPT` parse it that way,
+    and a bare token string would decode as unparseable legacy data, making
+    the holder unable to release its own lock.
+    """
+    stored = await redis.set(
+        key,
+        json.dumps({"token": token}, separators=(",", ":")),
+        nx=True,
+        ex=ttl_seconds,
+    )
+    return bool(stored)
+
+
+async def release_scoped_lock(redis: Redis, key: str, token: str) -> bool:
+    """Release a lock taken with acquire_scoped_lock(), if still owned."""
+    return bool(await redis.eval(_RELEASE_LOCK_SCRIPT, 1, key, token or ""))
+
+
 async def check_agent_type_online(
     redis: Redis,
     agent_type: str,
@@ -1225,6 +1252,10 @@ class WorkerRegistry:
             "active": self._get_int_hash_value(raw_counts, "active_count"),
             "queued": self._get_int_hash_value(raw_counts, "queued_count"),
             "running": self._get_int_hash_value(raw_counts, "running_count"),
+            "waiting_agent": self._get_int_hash_value(
+                raw_counts, "waiting_agent_count"
+            ),
+            "waiting_user": self._get_int_hash_value(raw_counts, "waiting_user_count"),
             "cancelling": self._get_int_hash_value(raw_counts, "cancelling_count"),
             "completed": self._get_int_hash_value(raw_counts, "completed_count"),
             "failed": self._get_int_hash_value(raw_counts, "failed_count"),
@@ -1245,6 +1276,10 @@ class WorkerRegistry:
         status_counts = {
             "QUEUED": counts["queued"],
             "RUNNING": counts["running"],
+            # Suspended callers persist as WAITING_* rather than QUEUED; these
+            # rows keep them visible (zero-valued entries are filtered below).
+            "WAITING_AGENT": counts["waiting_agent"],
+            "WAITING_USER": counts["waiting_user"],
             "CANCELLING": counts["cancelling"],
             "COMPLETED": counts["completed"],
             "FAILED": counts["failed"],

by_framework/core/wait_gate.py

@@ -0,0 +1,209 @@
+"""Idempotency gate for replies that resume a suspended caller.
+
+A suspended caller is woken by exactly one ``ResumeCommand``. Once a sweep
+can *synthesize* that reply (a callee whose worker died will never send
+one), two copies can exist for the same wait: the synthesized one and the
+real one that shows up late. Waking the caller twice re-runs a finished
+execution and, in a Task Group, pushes ``completed`` past ``total`` and
+aggregates a second time.
+
+The gate is the single place that decides which copy wins. It runs at the
+one point every reply passes through — right after a reply is parsed,
+before any registry lookup and before Task Group join accounting — and
+claims the caller's wait-index entry with a ``ZREM``. Exactly one claimant
+can win, because ``ZREM`` is atomic.
+
+The hard part is what ``ZREM`` returning 0 means, since it conflates two
+opposite situations:
+
+* the entry existed and someone else already claimed it — a true duplicate,
+  drop it;
+* the entry never existed — the reply belongs to a dispatch made before
+  this version shipped, or to a wait whose entry expired. Dropping it
+  silently loses a real reply, and during a rolling upgrade *every*
+  in-flight reply looks like this.
+
+A short-lived "consumed" marker written by the winner separates them: a 0
+with a marker is a duplicate, a 0 without one is unregistered and must be
+let through. When in doubt the gate lets the message through — a spurious
+extra wake-up is recoverable, a dropped reply is permanent silence. The
+same rule makes the gate fail *open*: any Redis error here allows the
+message.
+"""
+
+from typing import Any, NamedTuple
+
+from by_framework.common.constants import WAIT_CONSUMED_TTL_SECONDS, RedisKeys
+from by_framework.common.logger import logger
+from by_framework.core.protocol.commands import GatewayCommand
+from by_framework.core.wait_index import (
+    encode_member,
+    member_digest,
+    member_from_resume,
+    wait_index_key,
+)
+
+# Why a reply was allowed through / dropped. Carried on the decision so the
+# caller can log it and put it on the orphaned_reply event.
+ALLOW_CLAIMED = "claimed"
+ALLOW_UNREGISTERED = "unregistered"
+ALLOW_GATE_ERROR = "gate_error"
+DENY_ALREADY_CONSUMED = "already_consumed"
+
+
+class WaitGateDecision(NamedTuple):
+    """Outcome of the gate.
+
+    Attributes:
+        allow: Whether the reply may be processed. False only when the wait
+            it targets is provably already resolved.
+        reason: One of the ALLOW_*/DENY_* constants above.
+        member: The wait-index member the decision was made about ("" when
+            no candidate matched).
+    """
+
+    allow: bool
+    reason: str
+    member: str = ""
+
+
+def consumed_marker_key(session_id: str, member: str) -> str:
+    """Redis key of the "already consumed" marker for one wait-index member.
+
+    Part of the cross-SDK contract, since any SDK's worker may gate another
+    SDK's reply — see ``wait_index.member_digest`` for why the member is
+    hashed rather than embedded.
+    """
+    return RedisKeys.wait_consumed(session_id, member_digest(member))
+
+
+def candidate_members(command: GatewayCommand) -> list[str]:
+    """Wait-index members this reply could be clearing, most-specific first.
+
+    Normally there is exactly one: the member rebuilt from the reply's own
+    header. The second candidate covers ``ask_user``, which registers with
+    an empty ``child_message_id`` because it has no sub-task — while the
+    matching reply comes from a client that is free to put anything in
+    ``header.parent_message_id`` (existing callers put the caller's own
+    parent there, not an empty string), so it cannot be rebuilt exactly.
+
+    Order matters, and so does the fact that each candidate is fully
+    resolved (claim, then check its marker) before the next is tried: a
+    duplicate sub-agent reply must be caught by *its own* marker rather than
+    fall through and clear a live ask_user wait that happens to belong to
+    the same caller.
+
+    A reply carrying a ``task_group_id`` is a sub-agent reply by
+    construction, so the ask_user variant is not even considered for it.
+    """
+    header = command.header
+    members = [member_from_resume(command)]
+    if not header.task_group_id:
+        ask_user_member = encode_member(
+            session_id=header.session_id,
+            parent_message_id=header.message_id,
+            child_message_id="",
+            task_group_id="",
+        )
+        if ask_user_member not in members:
+            members.append(ask_user_member)
+    return members
+
+
+async def _mark_consumed(redis: Any, session_id: str, member: str) -> None:
+    """Record that this wait was resolved, so a late twin can be recognized.
+
+    Fail-soft: losing the marker only means a much later duplicate would be
+    allowed through (one extra wake-up), which is the direction this whole
+    module errs in anyway.
+    """
+    try:
+        await redis.set(
+            consumed_marker_key(session_id, member),
+            "1",
+            ex=WAIT_CONSUMED_TTL_SECONDS,
+        )
+    except Exception as error:  # pylint: disable=broad-exception-caught
+        logger.warning(
+            "Failed to mark wait entry consumed (session=%s): %s", session_id, error
+        )
+
+
+async def consume_wait_entry(redis: Any, command: GatewayCommand) -> WaitGateDecision:
+    """Claim the wait a reply resolves; report whether it may be processed.
+
+    Call once per ``ResumeCommand``, before the execution lookup and before
+    Task Group join accounting.
+    """
+    session_id = command.header.session_id
+    try:
+        index_key = wait_index_key(session_id)
+        for member in candidate_members(command):
+            removed = int(await redis.zrem(index_key, member) or 0)
+            if removed > 0:
+                await _mark_consumed(redis, session_id, member)
+                return WaitGateDecision(True, ALLOW_CLAIMED, member)
+            if await redis.exists(consumed_marker_key(session_id, member)):
+                return WaitGateDecision(False, DENY_ALREADY_CONSUMED, member)
+        # No entry, no marker: nobody ever registered this wait (a dispatch
+        # from before this version, or an entry that outlived its index).
+        # Unknown is not the same as duplicate — let it through.
+        return WaitGateDecision(True, ALLOW_UNREGISTERED)
+    except Exception as error:  # pylint: disable=broad-exception-caught
+        # Fail open. A gate that drops messages when Redis hiccups is worse
+        # than the duplicate it was built to prevent.
+        logger.warning(
+            "Wait-index gate unavailable for session=%s, allowing reply: %s",
+            session_id,
+            error,
+        )
+        return WaitGateDecision(True, ALLOW_GATE_ERROR)
+
+
+async def emit_orphaned_reply(
+    redis: Any,
+    command: GatewayCommand,
+    *,
+    worker_id: str = "",
+    reason: str = DENY_ALREADY_CONSUMED,
+) -> None:
+    """Announce on the session data stream that a reply was dropped.
+
+    A dropped reply is not noise: the sub-agent ran, produced a result, and
+    may have had side effects that nobody will now account for. Emitting it
+    on the existing data plane keeps it visible without inventing a second
+    reporting mechanism.
+
+    Fail-soft by construction — the drop/allow decision has already been
+    made, and reporting it must never change or block it.
+    """
+    header = command.header
+    try:
+        from by_framework.common.emitter import GatewayDataEmitter
+        from by_framework.core.protocol.event_type import EventType
+
+        await GatewayDataEmitter(redis_client=redis).emit_event(
+            session_id=header.session_id,
+            trace_id=header.trace_id,
+            event_type=EventType.ORPHANED_REPLY.value,
+            source_agent_type=header.source_agent_type,
+            message_id=header.message_id,
+            parent_message_id=header.parent_message_id,
+            data={
+                "reason": reason,
+                # The suspended caller this reply was addressed to...
+                "caller_message_id": header.message_id,
+                # ...and the sub-task that produced it (empty for ask_user).
+                "child_message_id": header.parent_message_id,
+                "task_group_id": header.task_group_id,
+                "status": str(getattr(command, "status", "") or ""),
+                "worker_id": worker_id,
+            },
+        )
+    except Exception as error:  # pylint: disable=broad-exception-caught
+        logger.warning(
+            "Failed to emit orphaned_reply event (session=%s, message_id=%s): %s",
+            header.session_id,
+            header.message_id,
+            error,
+        )