agentwire-dev 1.68.0__tar.gz → 1.70.0__tar.gz

{agentwire_dev-1.68.0 → agentwire_dev-1.70.0}/.github/workflows/pytest.yml

@@ -10,7 +10,7 @@
 # is on PATH. Per the council guardrail we do NOT chase coverage % or block PRs
 # on flaky/tmux-dependent tests.
 #
-# Coverage is measured and surfaced (term-missing in the log + a table in the
+# On pushes to main, coverage is measured and surfaced (term-missing in the log + a table in the
 # run's job summary + an uploaded coverage.xml artifact) but is REPORT-ONLY:
 # there is deliberately no --cov-fail-under, so a low percentage never reds the
 # build. The point is visibility — letting the maintainer spot untested
@@ -37,13 +37,22 @@ jobs:
       - name: Sync dependencies
         run: uv sync --extra dev
 
-      - name: Run test suite (tmux-dependent tests deselected) + coverage
+      # Pull requests run the FAST set: no coverage tracing (it multiplies
+      # runtime on a hosted runner) and no `slow` tests (real git/tmux
+      # processes per test). A PR gate that takes 45 minutes gets bypassed.
+      - name: Run test suite (fast set)
+        if: github.event_name == 'pull_request'
+        run: uv run --no-sync pytest -q -m "not requires_tmux and not slow"
+
+      # Pushes to main run everything hermetic, with the report-only coverage.
+      - name: Run test suite (full) + coverage
+        if: github.event_name != 'pull_request'
         run: >
           uv run --no-sync pytest -q -m "not requires_tmux"
           --cov=agentwire --cov-report=term-missing --cov-report=xml
 
       - name: Publish coverage summary (report-only)
-        if: always()
+        if: github.event_name != 'pull_request' && always()
         run: |
           {
             echo '## Coverage (report-only — no threshold gate)'
@@ -54,7 +63,7 @@ jobs:
           } >> "$GITHUB_STEP_SUMMARY"
 
       - name: Upload coverage.xml artifact
-        if: always()
+        if: github.event_name != 'pull_request' && always()
         uses: actions/upload-artifact@v4
         with:
           name: coverage-xml

{agentwire_dev-1.68.0 → agentwire_dev-1.70.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: agentwire-dev
-Version: 1.68.0
+Version: 1.70.0
 Summary: Multi-session voice web interface for AI coding agents
 Project-URL: Homepage, https://agentwire.dev
 Project-URL: Repository, https://github.com/dotdevdotdev/agentwire-dev

{agentwire_dev-1.68.0 → agentwire_dev-1.70.0}/agentwire/__init__.py

@@ -1,3 +1,3 @@
 """AgentWire - Multi-session voice web interface for AI coding agents."""
 
-__version__ = "1.68.0"
+__version__ = "1.70.0"

{agentwire_dev-1.68.0 → agentwire_dev-1.70.0}/agentwire/__main__.py

@@ -183,7 +183,7 @@ Command Categories:
     #   - diff:   structured git diff for the mobile Review window
     #   - prompts: prompt routing (rides the limits watchdog)
     #   - msg:    polite agent-to-agent inbox (rides the watchdog)
-    from . import diff_cli, limits_cli, msg_cli, pane_cli, prompts_cli, send_cli  # noqa: I001  # session_cli kept on its own line below to minimize Phase 1 #495 merge conflicts
+    from . import activity_cli, alerts_cli, diff_cli, limits_cli, msg_cli, pane_cli, prompts_cli, send_cli  # noqa: I001  # session_cli kept on its own line below to minimize Phase 1 #495 merge conflicts
     from . import session_cli
     from . import channels_cli, config_cli, portal_cli, tts_cli
     from . import scheduler_cli, ensure_cli, tasks_cli
@@ -191,12 +191,15 @@ Command Categories:
     from . import handoff_cli, hooks_cli, mcp_cli, roles_cli, tunnels_cli
     from . import notify_cli, palette_cli, push_cli, repo_cli, system_cli, wiki_cli
     from . import restart_cli, tabs_cli, wait_cli, worktree_cli
+    from . import buddy_cli  # BETA: gated on beta.voice_layer (default off)
     from .council import cli as council_cli
 
     _REGISTRARS = [  # noqa: N806  # registry constant; Phase 1 of #495 appends here
         diff_cli.register_diff_parser,
         prompts_cli.register_prompts_parser,
         msg_cli.register_msg_parser,
+        alerts_cli.register_alerts_parser,
+        activity_cli.register_activity_parser,
         limits_cli.register_limits_parser,
         pane_cli.register_pane_parser,
         send_cli.register_send_parser,
@@ -228,6 +231,7 @@ Command Categories:
         tabs_cli.register_tabs_parser,
         wait_cli.register_wait_parser,
         worktree_cli.register_helper_parser,
+        buddy_cli.register_buddy_parser,
     ]
     for _reg in _REGISTRARS:
         _reg(subparsers)

agentwire_dev-1.70.0/agentwire/activity_cli.py

@@ -0,0 +1,86 @@
+"""``agentwire activity`` — what the fleet has been doing (#1016).
+
+The read side of :mod:`~agentwire.fleet_activity`. It exists as a CLI verb for
+two reasons, and the second is the load-bearing one:
+
+1. "CLI is the single source of truth" — a store readable only from inside the
+   process tree that writes it is exactly the shape that rule exists to prevent.
+2. The voice layer dispatches **only** through the CLI (see
+   ``voice_layer/tools.py``), so without this verb the buddy could not read the
+   ledger that was built for it.
+
+Read-only, by construction: nothing here writes. Producers record from inside
+the surfaces that generate the events (idle, say, toast, scheduled run), never
+from a verb an agent could be talked into calling.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import timedelta
+
+from . import fleet_activity
+
+#: Widest window the verb will look back over. The ledger is capped at
+#: ``MAX_ENTRIES`` anyway, so this bounds the ANSWER rather than the read: a
+#: request for a week of awareness is a request for history, and
+#: ``agentwire scheduler history`` / the event logs are where history lives.
+MAX_HOURS = 72
+
+
+def cmd_activity_list(args) -> int:
+    json_mode = getattr(args, "json", False)
+    hours = max(1, min(MAX_HOURS, int(getattr(args, "hours", 12) or 12)))
+    entries = fleet_activity.recent(
+        limit=max(1, int(getattr(args, "limit", 50) or 50)),
+        event=getattr(args, "event", "") or "",
+        session=getattr(args, "session", "") or "",
+        window=timedelta(hours=hours),
+    )
+    if json_mode:
+        print(json.dumps({
+            "success": True,
+            "count": len(entries),
+            "window_hours": hours,
+            "ledger": str(fleet_activity.ledger_path()),
+            "activity": entries,
+        }, indent=2))
+        return 0
+    if not entries:
+        print(f"No fleet activity recorded in the last {hours}h.")
+        return 0
+    for entry in entries:
+        # The announced flag is shown, not hidden: "recorded" and "said out
+        # loud" are different facts, and an operator debugging a chatty or a
+        # silent buddy needs to see which one an entry was.
+        mark = "*" if entry.get("announced") else " "
+        print(f"{mark} {entry.get('ts', '')}  {entry.get('event', ''):<16} "
+              f"{entry.get('text', '')}")
+    print()
+    print("* = also queued to fleet-alert subscribers (spoken by the voice buddy at a gap)")
+    return 0
+
+
+def register_activity_parser(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "activity",
+        help="What the fleet has been doing (idle, tasks, toasts, speech)",
+        description=(
+            "The fleet's activity ledger: sessions going idle, scheduled tasks "
+            "finishing, toasts shown to the owner, and everything spoken aloud "
+            "through fleet TTS. This is AWARENESS — a record something can read "
+            "when asked. Only a short, ruled subset is also queued to "
+            "fleet-alert subscribers (see `agentwire alerts`); the rest waits "
+            "here to be looked up."
+        ),
+    )
+    sub = parser.add_subparsers(dest="activity_command", required=True)
+
+    p = sub.add_parser("list", help="Recent activity, newest first")
+    p.add_argument("--limit", type=int, default=50, help="Max entries (default: 50)")
+    p.add_argument("--hours", type=int, default=12,
+                   help=f"How far back to look (1-{MAX_HOURS}, default: 12)")
+    p.add_argument("--event", choices=fleet_activity.EVENTS, help="Only this event type")
+    p.add_argument("-s", "--session", help="Only this session (exact name)")
+    p.add_argument("--json", action="store_true", help="Output JSON")
+    p.set_defaults(func=cmd_activity_list)

agentwire_dev-1.70.0/agentwire/alerts_cli.py

@@ -0,0 +1,153 @@
+"""``agentwire alerts`` — who hears the machine's own detectors (#982).
+
+Fleet detectors (expired login, usage-limit park, dead-lettered report-backs, a
+root pane blocked with nowhere to route) have always been able to email the
+OWNER. ``fleet_alerts`` lets them address a SESSION as typed mail instead, and
+this is the surface that turns that on: without a CLI verb the subscription API
+would be reachable only from inside the tree that calls it, which is precisely
+the shape "CLI is the single source of truth" exists to prevent.
+
+Subscription is a renewable **lease**, so ``list`` reports the expiry rather
+than a boolean: a subscriber that stopped renewing has silently stopped
+hearing anything, and that is a state an operator has to be able to see.
+"""
+
+from __future__ import annotations
+
+import json
+
+from . import fleet_alerts
+
+
+def _emit(payload: dict, json_mode: bool, lines: "list[str] | None" = None) -> int:
+    if json_mode:
+        print(json.dumps(payload, indent=2))
+    else:
+        for line in lines or []:
+            print(line)
+    return 0 if payload.get("success", True) else 1
+
+
+def cmd_alerts_subscribe(args) -> int:
+    json_mode = getattr(args, "json", False)
+    try:
+        lease = fleet_alerts.subscribe(args.session)
+    except Exception as exc:
+        return _emit(
+            {"success": False, "error": str(exc)}, json_mode, [f"error: {exc}"]
+        )
+    return _emit(
+        {"success": True, "session": args.session, "lease": lease},
+        json_mode,
+        [
+            f"'{args.session}' now receives fleet alerts.",
+            f"  lease expires: {lease['expires_at']}",
+            "  Renew before then — an expired lease goes quiet, it does not warn.",
+        ],
+    )
+
+
+def cmd_alerts_unsubscribe(args) -> int:
+    json_mode = getattr(args, "json", False)
+    dropped = fleet_alerts.unsubscribe(args.session)
+    if not dropped:
+        return _emit(
+            {"success": False, "error": f"'{args.session}' was not subscribed"},
+            json_mode,
+            [f"'{args.session}' was not subscribed."],
+        )
+    return _emit(
+        {"success": True, "session": args.session},
+        json_mode,
+        [f"'{args.session}' no longer receives fleet alerts."],
+    )
+
+
+def cmd_alerts_list(args) -> int:
+    """Who is subscribed — and whether this answer can be trusted.
+
+    ``list`` reads the same candidate index the emit path does, so a lost index
+    makes both of them say "nobody". That would be the worst property this
+    command could have: the one surface built to make a silent stop VISIBLE
+    would agree with the silent stop. So the index's presence is reported
+    alongside the answer, and its absence is not rendered as a confident zero.
+    """
+    json_mode = getattr(args, "json", False)
+    names = fleet_alerts.subscribers()
+    index_present = fleet_alerts.subscribers_index_path().exists()
+    rows = [{"session": n, "lease": fleet_alerts.subscription(n)} for n in names]
+    if names:
+        lines = [
+            "Sessions receiving fleet alerts:",
+            *(f"  {r['session']}  (lease expires {(r['lease'] or {}).get('expires_at')})"
+              for r in rows),
+        ]
+    elif index_present:
+        lines = ["No session is subscribed to fleet alerts."]
+    else:
+        lines = [
+            "No subscriber index — so this is NOT a confident 'nobody subscribed'.",
+            "Either nobody ever subscribed, or the index was lost; from here those "
+            "look identical, and while it is missing every alert reaches nobody.",
+            "Settle it (cheap, and it rebuilds the index either way):",
+            "  agentwire alerts reindex",
+        ]
+    return _emit(
+        {
+            "success": True,
+            "subscribers": names,
+            "leases": rows,
+            "index_present": index_present,
+        },
+        json_mode,
+        lines,
+    )
+
+
+def cmd_alerts_reindex(args) -> int:
+    """Rebuild the candidate index from the session records.
+
+    The alert path never walks the record store — that cost sits on the
+    synchronous permission-hook path — so a lost index means fewer alerts until
+    somebody rebuilds it. This is that somebody.
+    """
+    json_mode = getattr(args, "json", False)
+    names = fleet_alerts.reindex()
+    return _emit(
+        {"success": True, "subscribers": names},
+        json_mode,
+        [f"Reindexed: {len(names)} live subscriber(s)." , *(f"  {n}" for n in names)],
+    )
+
+
+def register_alerts_parser(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "alerts",
+        help="Who hears the machine's own detectors (fleet alerts)",
+        description=(
+            "Fleet detectors — expired login, usage-limit park, dead-lettered "
+            "report-backs, a root pane blocked with nowhere to route — email the "
+            "owner. They can also address a SESSION as typed mail: an escalation "
+            "for the two conditions only a human can clear, a note or a request "
+            "for the rest. A session subscribes here, on a renewable lease."
+        ),
+    )
+    sub = parser.add_subparsers(dest="alerts_command", required=True)
+
+    p = sub.add_parser("subscribe", help="Lease fleet alerts for a session")
+    p.add_argument("session", help="Session name (must have a session record)")
+    p.add_argument("--json", action="store_true", help="JSON output")
+    p.set_defaults(func=cmd_alerts_subscribe)
+
+    p = sub.add_parser("unsubscribe", help="Drop a session's fleet-alert lease")
+    p.add_argument("session")
+    p.add_argument("--json", action="store_true", help="JSON output")
+    p.set_defaults(func=cmd_alerts_unsubscribe)
+
+    p = sub.add_parser("list", help="Sessions with a live lease, and its expiry")
+    p.add_argument("--json", action="store_true", help="JSON output")
+    p.set_defaults(func=cmd_alerts_list)
+
+    p = sub.add_parser("reindex", help="Rebuild the subscriber index from records")
+    p.add_argument("--json", action="store_true", help="JSON output")
+    p.set_defaults(func=cmd_alerts_reindex)

{agentwire_dev-1.68.0 → agentwire_dev-1.70.0}/agentwire/auth_expired.py

@@ -360,8 +360,10 @@ def record_outage(detail: dict, source: str = "ensure") -> dict:
         "source": source,
         "host": socket.gethostname(),
         "escalated_at": prior.get("escalated_at"),
+        "alerted_at": prior.get("alerted_at"),
     }
     state["escalated_at"] = _escalate(state, prior)
+    state["alerted_at"] = _alert_fleet(state, prior)
     write_state(state)
     log_event("outage_detected", session=detail.get("session"),
               transcript=detail.get("transcript"), source=source)
@@ -421,6 +423,50 @@ def _escalate(state: dict, prior: dict) -> str | None:
     return previous
 
 
+def _alert_fleet(state: dict, prior: dict) -> "str | None":
+    """Tell subscribed sessions, on the same clock the owner email rides (#982).
+
+    Escalation kind, and this is the clearest case for it in the fleet: the
+    outage is machine-wide, every subsequent turn is refused, and nothing but a
+    human running ``/login`` can clear it. It is bounded to once per
+    :data:`ESCALATE_TTL` per outage — machine-wide, not per session and not per
+    dispatch — which is what makes an interrupt affordable here.
+
+    Stamped separately from ``escalated_at`` while sharing that field's state
+    record and its TTL. Not a parallel throttle store — the same file, the same
+    window — but a separate stamp, because the two channels fail differently:
+    the email deliberately retries per detection when the provider is down
+    (only a successful send stamps), and an alert inheriting that retry would
+    turn a broken Resend key into one interrupt per dispatch. Enqueueing is a
+    local write, so this stamp lands whenever the alert actually did.
+    """
+    previous = prior.get("alerted_at")
+    if previous:
+        try:
+            if _now() - datetime.fromisoformat(previous) < ESCALATE_TTL:
+                return previous
+        except (TypeError, ValueError):
+            pass
+    try:
+        from . import fleet_alerts
+
+        sessions = ", ".join(state.get("sessions") or []) or "(none recorded)"
+        reached = fleet_alerts.emit_for(
+            "auth_expired",
+            f"Claude login expired on {state.get('host')} — every turn is being "
+            f"refused ({RENDERED}). Sessions hit so far: {sessions}. Scheduled "
+            f"dispatch is gated until someone runs /login; nothing recovers on "
+            f"its own. First seen {state.get('detected_at')}.",
+        )
+    except Exception as exc:  # alerting is best-effort; never break the gate
+        log_event("alert_failed", error=str(exc))
+        return previous
+    if not reached:
+        return previous
+    log_event("alerted", sessions=state.get("sessions"), to=reached)
+    return _now().isoformat()
+
+
 def check_and_flag(
     session: str, project_path=None, since: float | None = None, source: str = "ensure"
 ) -> dict | None:

agentwire_dev-1.70.0/agentwire/beta.py

@@ -0,0 +1,193 @@
+"""``agentwire.beta`` — the one implementation of the beta gate.
+
+A beta feature ships on ``main`` and stays off until a user asks for it. The
+flag VALUES live in :mod:`agentwire.config` (``BetaConfig``); the MECHANICS of
+hiding gated text live here, because the same mechanism now serves two
+model-facing surfaces and a third would otherwise grow its own copy:
+
+- **role prompts** (markdown) — resolved in ``roles.parse_role_file``;
+- **MCP tool descriptions** (docstrings) — resolved by :func:`gated_doc`.
+
+Both are text a model reads and a user pays tokens for, which is the property
+that decides what belongs behind a gate. The MCP schema was missed on the first
+pass: ``msg_send``'s description grew ~316 characters of voice-buddy prose that
+loaded into every agent session in every install, ungated, while the commit
+message asserted the role prompts were the only such surface. The lesson is in
+this module's existence — one gate, one place, and a byte-identity proof per
+surface rather than per file.
+"""
+
+from __future__ import annotations
+
+import re
+
+#: A gated region:
+#:
+#:     <!-- beta:voice_layer -->
+#:     ...text that only ships when beta.voice_layer is on...
+#:     <!-- /beta:voice_layer -->
+#:
+#: Leading whitespace is allowed on both markers (a docstring cannot put them in
+#: column 0) and the close tag may end the string with no trailing newline. Both
+#: shapes previously failed OPEN — the region simply did not match, and its text
+#: shipped ungated, which is the one failure direction a gate may not have.
+#:
+#: The backreference means open and close must name the SAME flag, so a mistyped
+#: close tag matches nothing. That case still fails open — it cannot be resolved
+#: without guessing where the region ends — and is caught instead by the audit
+#: in ``tests/unit/test_beta_flag.py``, which asserts no marker-shaped text
+#: survives :func:`apply_beta_blocks` in any shipped role file.
+BETA_BLOCK_RE = re.compile(
+    r"^[ \t]*<!-- beta:([a-z0-9_]+) -->[ \t]*\n(.*?)^[ \t]*<!-- /beta:\1 -->[ \t]*(?:\n|\Z)",
+    re.MULTILINE | re.DOTALL,
+)
+
+#: Anything marker-SHAPED, paired or not. The audit's instrument: what
+#: :data:`BETA_BLOCK_RE` leaves behind is exactly the set of broken markers.
+LOOSE_MARKER_RE = re.compile(r"<!--\s*/?\s*beta:[^>]*-->")
+
+#: A stray marker on its own line, removed at render time only — see
+#: :func:`render` for why that is deliberately NOT done in
+#: :func:`apply_beta_blocks`.
+_STRAY_MARKER_LINE_RE = re.compile(
+    r"^[ \t]*<!--\s*/?\s*beta:[^>]*-->[ \t]*(?:\n|\Z)", re.MULTILINE
+)
+
+_CACHE: "set[str] | None" = None
+
+
+def flag_names() -> frozenset[str]:
+    """The flags a marker may legally name. Owned by :mod:`agentwire.config`."""
+    from .config import BETA_FLAG_NAMES
+
+    return BETA_FLAG_NAMES
+
+
+def enabled_flags() -> set[str]:
+    """Which beta features are on, cached for the life of the process.
+
+    Cached because the gate sits on a hot path: ``parse_role_file`` runs once
+    per role per session launch, and an uncached read cost a full
+    ``load_config`` — with its stderr INFO line — each time, taking ``roles
+    list`` from 11ms to 242ms and printing 24 log lines, for a feature almost
+    nobody has enabled.
+
+    The consequence is stated rather than hidden: a long-lived process
+    observes the flag state it started with, so turning a beta feature on takes
+    the restart that ``config.yaml`` changes already take. An import-time
+    surface like an MCP tool description is process-lifetime by construction
+    anyway. :func:`reset_cache` exists for tests.
+
+    **The precondition that makes the ON direction safe, written down because
+    it is not visible from here.** A cached ``{"voice_layer"}`` outlives a
+    config that has since said off — verified: gated prose keeps rendering
+    until :func:`reset_cache`. That is unreachable today only because every
+    in-process caller of ``load_roles``/``parse_role_file`` is a short-lived
+    CLI module, and the surfaces that look long-lived are not: ``role show``
+    and ``roles list`` shell out through ``run_agentwire_cmd``, so each render
+    happens in a fresh process that re-reads the flag.
+
+    **A long-lived in-process caller would violate that**, and would do it
+    silently — the gate would keep a feature ON for a user who turned it off,
+    with no error anywhere. If you add one (a portal route rendering role text
+    in-process, a daemon calling ``parse_role_file``), either call
+    :func:`reset_cache` at the top of each request or give that caller an
+    explicit ``enabled`` set. Do not discover this precondition by tripping it.
+    """
+    global _CACHE
+    if _CACHE is None:
+        from .config import enabled_beta_flags
+
+        _CACHE = enabled_beta_flags()
+    return _CACHE
+
+
+def reset_cache() -> None:
+    """Drop the cached flag set (tests; a process that rewrote its own config)."""
+    global _CACHE
+    _CACHE = None
+
+
+def apply_beta_blocks(text: str, enabled: set[str]) -> str:
+    """Resolve every PAIRED gated region in *text*.
+
+    Enabled flag → the body ships, with the marker lines removed (they are
+    scaffolding, and shipping them would cost the tokens the gate exists to
+    save). Disabled — or a flag name nothing knows about — → the whole region
+    goes, markers included.
+
+    **An unknown flag fails CLOSED**, and that direction is chosen rather than
+    inherited: text no gate can turn off is precisely the failure this module
+    exists to prevent. What makes it safe rather than silent is the paired
+    audit — a test fails on any marker naming a flag ``config.BETA_FLAG_NAMES``
+    does not know, so a typo is caught before it can delete a section forever.
+
+    Deliberately does NOT remove unpaired markers: this function's output is
+    what the audit measures, and swallowing broken markers here would make that
+    audit unable to fail. :func:`render` does that, at the edge.
+    """
+    known = flag_names()
+
+    def _resolve(match: "re.Match") -> str:
+        flag, body = match.group(1), match.group(2)
+        return body if (flag in known and flag in enabled) else ""
+
+    return BETA_BLOCK_RE.sub(_resolve, text)
+
+
+def render(text: str, enabled: "set[str] | None" = None) -> str:
+    """Resolve gated regions for text about to reach a model.
+
+    :func:`apply_beta_blocks`, then strip any marker line left over. That second
+    step fixes only the smaller half of a broken marker: the region it was meant
+    to wrap is still ungated (the audit is what catches that), but the
+    scaffolding itself never reaches the model as prose.
+    """
+    # Text with no marker cannot change, so it must not pay for the flag
+    # lookup — that is 20 of the 24 shipped role files and 107 of the 108 MCP
+    # tool descriptions, several of which resolve at IMPORT time. Cheap
+    # substring scan, and it keys on the same literal the regexes do.
+    if enabled is None:
+        if "beta:" not in text:
+            return text
+        enabled = enabled_flags()
+    return _STRAY_MARKER_LINE_RE.sub("", apply_beta_blocks(text, enabled))
+
+
+def gated_doc(fn):
+    """Resolve gated regions in a function's docstring, in place.
+
+    For MCP tools, apply it BELOW ``@mcp.tool()`` so FastMCP reads the resolved
+    text::
+
+        @mcp.tool()
+        @gated_doc
+        def msg_send(...):
+            \"\"\"...\"\"\"
+
+    Decorators apply bottom-up, so the docstring is already resolved by the time
+    the tool is registered — and FastMCP snapshots the docstring AT
+    registration, publishing it as the tool description, which is what makes
+    this the whole fix.
+
+    **Inverting the two silently un-gates the tool**, measured rather than
+    feared: with ``@gated_doc`` above ``@mcp.tool()`` the raw text publishes,
+    markers and all (2165 chars vs 1800). Nothing about the wrong order looks
+    wrong, so the property is pinned over the WHOLE registry —
+    ``test_no_published_description_carries_a_marker`` fails on any published
+    description containing a marker, whatever put it there.
+
+    The resolution happens ONCE, at import, against whatever flag state the
+    process started with — so any later reader that wants to verify the
+    resolved text needs to know which flags it was resolved WITH, not which
+    flags are on now. ``__beta_enabled__`` records exactly that (and
+    ``__beta_raw_doc__`` the pre-resolution text), which is what lets the
+    byte-identity tests hold on a machine with a beta flag enabled instead of
+    silently asserting the developer's personal config (#1023).
+    """
+    if fn.__doc__ and "beta:" in fn.__doc__:
+        enabled = enabled_flags()
+        fn.__beta_raw_doc__ = fn.__doc__
+        fn.__beta_enabled__ = frozenset(enabled)
+        fn.__doc__ = render(fn.__doc__, enabled=enabled)
+    return fn