From 0c15487597ae41a119b2535115ca66cc481efb3e Mon Sep 17 00:00:00 2001
From: modusensus <guanqishi26@gmail.com>
Date: Mon, 21 Sep 2026 14:09:38 +0800
Subject: [PATCH] =?UTF-8?q?feat(serve):=20=E6=BC=94=E7=A4=BA=E6=97=B6?=
 =?UTF-8?q?=E9=92=9F=E5=8F=AF=E5=86=BB=E7=BB=93=E3=80=81=E5=8F=AF=E6=AD=A5?=
 =?UTF-8?q?=E8=BF=9B=E3=80=81=E5=8F=AF=E8=B7=B3=E5=88=B0=E4=B8=8B=E4=B8=80?=
 =?UTF-8?q?=E5=A4=84=E5=8F=98=E5=8C=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

--demo 的时间轴以前只能自己走：要看到故障态得干等 140 秒的健康段，而"看一眼前端长什么
样"的人多半已经在等第一轮了。现在页脚有一行"演示时钟"（说明现在看的是哪一刻）加五个
按钮：冻结 / −10s / +10s / 下一处变化 / 回到现在。

三个决定值得记下来。

1) 锚点是**读**，不是控制端点。时间轴本来就是"某个时刻的纯函数"，所以让那个时刻从请求里
来：?at=<秒>。服务端因此仍然不持有任何可变状态——没有要抢的锁、没有非幂等路由、没有"谁在
什么时候读到半个状态"，而且一个链接就是某一刻（截图把地址栏一并截下来就能自证）。为此
provider 契约改为接收这一次请求的查询串（ponte.serve.Provider），实时那条明确忽略它：真实
状态只有"现在"，?at=abc、负数、无穷、超大值一律回退到实时（上限一天）。

2) "下一处变化"跳的是**看得见**的变化，不是下一个阶段边界。web 的"断线 → 重连退避"两段
判定与两列端口完全一样，落在那里的按钮看起来就是坏的。所以判据跟着看板走
(_visible_state)，跳过看不出来的边界。测试不是镜像那句判据，而是拿渲染给看板的 payload
重算一遍：到目标之前的每半秒都必须与现在一模一样，到目标那一刻必须不同。

3) 冻结冻的是**数据**，不是刷新。页面照旧每 5 秒"已更新"，只是时刻不再推进——所以冻结的
看板是显然冻住了，而不是和挂掉的标签页长得一样。冻结状态下步进保持冻结：逐个状态看过去
正是这个功能的用法。页脚写明三种状态：实时 / 已固定 / 已冻结。

顺带：payload 的演示标记从 "demo": true 长成一个对象（at / anchored / next_at /
next_profile），仍是 payload 里唯一多出来的键，契约测试因此没变松；时刻与"下一处变化"必须
与看板同时到达客户端，否则按钮会基于过期的时刻跳。页脚的 status.json / metrics / healthz
链接带上锚点，免得看板钉在某一刻而 JSON 回答"现在"。

验证：449 测试、ruff、两个平台的 mypy、smoke 全过。四处反向对照都确认新测试抓得住：next
退化成"下一个边界"、handler 不传查询串、锚点不校验、实时路径认锚点。浏览器里逐个按钮点
过：冻结 7 秒后读数与 URL 都不动而"已更新"照常走、步进 +10s、两次"下一处变化"分别落在 db
的"端口没监听 → 断线"与 web 的断线上、回到现在把 ?at= 从地址栏去掉。

---------

Co-authored-by: Codebuff <noreply@codebuff.com>
---
 CHANGELOG.md                    |  27 ++++
 README.md                       |  29 +++-
 ponte/demo.py                   | 111 +++++++++++++-
 ponte/main.py                   |  14 +-
 ponte/serve.py                  | 262 ++++++++++++++++++++++++++++++--
 tests/test_demo.py              | 220 ++++++++++++++++++++++++++-
 tests/test_integration_serve.py |   2 +-
 tests/test_main.py              |   2 +-
 tests/test_serve.py             |  40 +++--
 9 files changed, 664 insertions(+), 43 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e9b4484..9352413 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -213,6 +213,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   not be mistakable for somebody's real infrastructure. Sample hosts are
   `example.com`. The bind rules are unchanged: a non-loopback `--host` still
   demands a token.
+- **The demo timeline can be pinned, stepped and frozen from the page.** Waiting
+  out a 140-second healthy stretch to reach the interesting state is a poor way to
+  look at a dashboard, and a demo that only moves on its own clock is one you
+  watch rather than use. `ponte serve --demo` now marks the moment it is showing
+  in the footer and offers `冻结` / `−10s` / `+10s` / `下一处变化` / `回到现在`
+  beside it. `下一处变化` jumps to the **next change that is visible on the
+  board**, not to the next phase boundary: a tunnel that moves from
+  "disconnected" to "retrying" renders identically (same verdict, same ports), so
+  a button that lands where nothing changed reads as broken — those boundaries are
+  skipped, which is asserted by re-deriving the board's visible state from the
+  rendered payload at every half-second up to the target. Freezing stops the
+  reading advancing *while the page keeps refreshing*, so a frozen board is
+  visibly frozen instead of being indistinguishable from a dead tab (the `已更新`
+  ticker keeps moving). Stepping while frozen deliberately stays frozen — walking
+  a fault state by state is the point. All of it is a **read**: the moment rides a
+  `?at=<seconds>` query and the server still holds no mutable state, which is why
+  a live `ponte serve` ignores the parameter entirely (`?at=abc`, negatives,
+  infinities and absurd values fall back to live, clamped at a day), why the four
+  endpoints stay idempotent, why two viewers of one URL see the same board, and
+  why a copied link reproduces the exact moment it was copied from. The footer's
+  `status.json` / `metrics` / `healthz` links carry the anchor with them, so a
+  pinned page does not hand out a JSON of *now*. To keep it a read the status
+  provider now receives the request's query (`ponte.serve.Provider`); the live
+  provider ignores it. The demo marker grew from `"demo": true` into
+  `"demo": {"at": …, "anchored": …, "next_at": …, "next_profile": …}` — still
+  the one extra key in `/status.json`, but the clock now travels with the data the
+  page renders, so the buttons cannot act on a stale moment.
 - **The jump chain is part of the status, next to the destination.**
   `ProfileStatus.jump` carries the `ssh -J` value, so `ponte status --json` and
   the dashboard can tell "cannot reach the server" apart from "cannot reach the
diff --git a/README.md b/README.md
index 0b7548f..02923ae 100644
--- a/README.md
+++ b/README.md
@@ -143,10 +143,19 @@ ponte serve --open     # ...and open it in your browser
 **No tunnels yet?** `ponte serve --demo` runs the same server on built-in sample
 data: a small timeline that connects, drops, backs off and reconnects on its own,
 so the page shows every state it has — healthy, broken, and *unknown* (a probe
-that could not answer). It reads no config and never touches a daemon, and the
-payload (`"demo": true`), the page header and the CLI output all say the data is
-a demo: a dashboard screenshot names your servers, so it must not be mistakable
-for somebody's real infrastructure. Sample hosts use `example.com`.
+that could not answer). A `演示时钟` line in the footer says which moment you are
+looking at, and `冻结` / `−10s` / `+10s` / `下一处变化` / `回到现在` next to it
+drive the timeline: `下一处变化` jumps to the next change that is *visible on the
+board*, so a fault state is one click away instead of 140 seconds of healthy
+staring (two adjacent phases that look identical are skipped — a button landing
+where nothing changed reads as broken). Those buttons only move a number in the
+URL (`?at=<seconds>`): the server holds no state, a live `ponte serve` ignores the
+parameter, and a copied link shows that exact moment to whoever opens it. It reads
+no config and never touches a daemon, and the payload
+(`"demo": {"at": …, "anchored": …, "next_at": …}`), the page header and the CLI
+output all say the data is a demo: a dashboard screenshot names your servers, so
+it must not be mistakable for somebody's real infrastructure. Sample hosts use
+`example.com`.
 
 | Endpoint | What it answers |
 |----------|-----------------|
@@ -470,9 +479,15 @@ ponte serve --open     # 顺手在浏览器里打开
 
 **还没有隧道？** `ponte serve --demo` 用内置的示例数据把同一个服务跑起来：一份自己会
 连接、断线、退避、重连的小时间轴，于是页面上该有的状态都会出现——健康、异常，以及
-**未知**（探针没能得出结论）。它不读配置、也不碰守护进程；payload（`"demo": true`）、
-页面头部与命令行输出三处都写明这是演示数据：看板截图里写着服务器地址与端口，它不该被
-误读成某个人的真实基础设施。示例主机名一律用 `example.com`。
+**未知**（探针没能得出结论）。页脚有一行 `演示时钟` 告诉你现在看的是哪一刻，旁边的
+`冻结` / `−10s` / `+10s` / `下一处变化` / `回到现在` 可以推着它走：`下一处变化` 跳到的是
+**看板上看得见**的下一次变化，于是你不用干等那 140 秒的健康段就能看到故障态（相邻但外观
+相同的两段会被跳过——落在一处什么都没变的地方，按钮看起来就是坏的）。这些按钮只是改
+地址栏里的一个数字（`?at=<秒>`）：服务端不持有任何状态、实时的 `ponte serve` 直接忽略
+它、复制出去的链接谁打开都是同一刻。它不读配置、也不碰守护进程；payload
+（`"demo": {"at": …, "anchored": …, "next_at": …}`）、页面头部与命令行输出三处都写明
+这是演示数据：看板截图里写着服务器地址与端口，它不该被误读成某个人的真实基础设施。
+示例主机名一律用 `example.com`。
 
 | 接口 | 回答什么问题 |
 |------|--------------|
diff --git a/ponte/demo.py b/ponte/demo.py
index b9b70cb..59502d5 100644
--- a/ponte/demo.py
+++ b/ponte/demo.py
@@ -19,6 +19,11 @@
 ===================  ==========================================================
 
 用法：``ponte serve --demo``（见 ``ponte.main.serve``）。
+
+时间轴可以被**钉在某一刻**：``?at=<秒>``（相对启动）。锚点是**读**而不是写——时间轴本来
+就是"某个时刻的纯函数"，所以让那个时刻从请求里来，服务端不必持有任何可变状态；去掉这个
+参数就回到实时。于是一个 URL 就能把看板固定在某一刻，截图里自帯"这是哪一刻"，而页面上的
+按钮只是会改地址栏里那个数字的便利层。
 """
 
 from __future__ import annotations
@@ -26,6 +31,7 @@
 import math
 import os
 import time
+from collections.abc import Mapping
 from dataclasses import dataclass
 from typing import Any
 
@@ -38,6 +44,9 @@
 #: 事件流保留多少条（与看板的 ``_FEED_LIMIT`` 对齐；多几条无妨，看板会自己截断）。
 _FEED_LIMIT = 8
 
+#: ``?at=`` 的上限：一天。更远的锚点没有意义，也顺手挡住离谱输入。
+_AT_LIMIT = 86_400.0
+
 #: 这些状态下 SSH 会话还活着——可用率因此把它们算成"在线"。
 _ALIVE_STATES = frozenset({CONNECTED, UNKNOWN})
 
@@ -141,6 +150,24 @@ def _is_up(state: str) -> bool:
     return state in _ALIVE_STATES
 
 
+def _parse_at(query: Mapping[str, list[str]] | None) -> float | None:
+    """读 ``?at=`` 锚点：一个非负的有限秒数，否则 ``None``（跟随墙上时钟）。
+
+    坏值一律回退到实时而不报错：这是只读的演示接口，打错一个参数不该让页面挂掉（尤其因为
+    地址栏里那个参数是按钮写上去的，刷新、手改、转发都可能弄出奇怪的值）。
+    """
+    values = (query or {}).get("at")
+    if not values:
+        return None
+    try:
+        at = float(values[0].strip())
+    except (AttributeError, TypeError, ValueError):
+        return None
+    if not math.isfinite(at) or at < 0:
+        return None
+    return min(at, _AT_LIMIT)
+
+
 def _phase_starts(profile: DemoProfile) -> list[float]:
     """每一段在循环内的起点（秒）。"""
     starts: list[float] = []
@@ -317,6 +344,57 @@ def _profile_payload(profile: DemoProfile, *, started: float, now: float) -> dic
     }
 
 
+def _visible_state(profile: DemoProfile, index: int) -> tuple[Any, ...]:
+    """看板在一段里渲染出来的"状态"：判定、结论是否确定、进程在不在、两列端口。
+
+    这是"**有没有变化**"的判据——它跟着看板走，而不是跟着阶段走（见 :func:`_next_change`）。
+    """
+    phase = profile.phases[index]
+    return (
+        phase.state == CONNECTED and not phase.reason,
+        phase.state != UNKNOWN,
+        _is_up(phase.state),
+        tuple(_port_state(phase, remote=True) for _ in profile.remote_ports),
+        tuple(_port_state(phase, remote=False) for _ in profile.local_ports),
+    )
+
+
+def _next_change(profile: DemoProfile, elapsed: float) -> tuple[float, int] | None:
+    """``elapsed`` 之后，这条隧道下一次可见的变化：(虚拟秒, 循环内第几段)。
+
+    判据是"看板上看得见的东西变了没有"，而不是"进入下一段"。理由具体：像 ``web`` 的
+    "断线 → 重连退避"那两段，判定、两列端口完全一样（页面上的字也几乎一样），中间那个边界
+    跳过去等于按钮失灵。所以拿 :func:`_visible_state` 比，跳过那些看不出来的边界。
+
+    周期是有限的，所以变化一定在"当前这一轮剩下的边界 + 下一轮"里，不需要无界搜索。
+    """
+    cycle = profile.cycle_seconds
+    starts = _phase_starts(profile)
+    current = _visible_state(profile, _locate(profile, elapsed % cycle))
+    base = int(elapsed // cycle)
+    for cycle_index in (base, base + 1):
+        for index, start in enumerate(starts):
+            when = cycle_index * cycle + start
+            if when <= elapsed:
+                continue
+            if _visible_state(profile, index) != current:
+                return when, index
+    return None  # pragma: no cover - 三个演示 profile 每一轮都会变
+
+
+def _next_change_at(elapsed: float) -> tuple[float, str, str] | None:
+    """全部 profile 里最近的一次可见变化：(虚拟秒, 哪条隧道, 变成什么状态)。"""
+    best: tuple[float, str, str] | None = None
+    for profile in _PROFILES:
+        found = _next_change(profile, elapsed)
+        if found is None:  # pragma: no cover - 见 _next_change
+            continue
+        when, index = found
+        if best is None or when < best[0]:
+            best = (when, profile.name, profile.phases[index].state)
+    return best
+
+
 def _port_state(phase: Phase, *, remote: bool) -> bool:
     """端口在某一刻的样子。
 
@@ -343,8 +421,14 @@ def __init__(self, *, started_at: float | None = None) -> None:
         #: 演示的"守护进程"就是提供看板的这个进程，pid 因此是真的。
         self.pid = os.getpid()
 
-    def payload(self, *, now: float | None = None) -> dict[str, Any]:
-        """某一刻的完整 payload（``now`` 可注入，便于测试钉住时刻）。"""
+    def payload(
+        self, *, now: float | None = None, anchored: bool = False
+    ) -> dict[str, Any]:
+        """某一刻的完整 payload（``now`` 可注入，便于测试钉住时刻）。
+
+        ``anchored`` 只描述"这一刻是怎么来的"（``?at=`` 钉住的，还是墙上时钟），供页面把
+        时钟标的诚实（"已固定" / "实时"）；它不影响任何一个数据字段。
+        """
         moment = time.time() if now is None else now
         profiles: dict[str, dict[str, Any]] = {}
         for profile in _PROFILES:
@@ -355,15 +439,30 @@ def payload(self, *, now: float | None = None) -> dict[str, Any]:
                 section["local_ports"] = {}
             profiles[profile.name] = section
         healthy = all(section["healthy"] for section in profiles.values())
+        elapsed = max(0.0, moment - self.started_at)
+        upcoming = _next_change_at(elapsed)
         return {
             "running": True,
             "pid": self.pid,
             "started_at": self.started_at,
-            "uptime_seconds": max(0.0, moment - self.started_at),
+            "uptime_seconds": elapsed,
             "healthy": healthy,
-            "demo": True,
+            # 一个对象而不是 ``true``：标记与"当前停在哪一刻、下一次变化在哪"是同一件事——
+            # 都是演示特有的，而且都必须与看板同时到达客户端（否则按钮会基于过期的时刻跳）。
+            # 它仍然是 payload 里唯一多出来的键，契约测试因此没变松。
+            "demo": {
+                "at": round(elapsed, 1),
+                "anchored": anchored,
+                "next_at": round(upcoming[0], 1) if upcoming else None,
+                "next_profile": upcoming[1] if upcoming else None,
+                "next_state": upcoming[2] if upcoming else None,
+            },
             "profiles": profiles,
         }
 
-    def __call__(self) -> dict[str, Any]:
-        return self.payload()
+    def __call__(self, query: Mapping[str, list[str]] | None = None) -> dict[str, Any]:
+        """``ponte serve`` 每次请求都调这个；``?at=`` 把这一刻钉在时间轴的任意位置。"""
+        at = _parse_at(query)
+        if at is None:
+            return self.payload(anchored=False)
+        return self.payload(now=self.started_at + at, anchored=True)
diff --git a/ponte/main.py b/ponte/main.py
index 533b67c..0151a54 100644
--- a/ponte/main.py
+++ b/ponte/main.py
@@ -17,7 +17,7 @@
 import sys
 import time
 import webbrowser
-from collections.abc import Callable
+from collections.abc import Mapping
 from pathlib import Path
 from typing import TYPE_CHECKING, NoReturn
 
@@ -44,7 +44,7 @@
 from ponte.daemon import _format_duration
 from ponte.demo import DemoStatus
 from ponte.doctor import FAIL, OK, SKIP, WARN, counts, run_checks
-from ponte.serve import create_server, serve_url
+from ponte.serve import Provider, create_server, serve_url
 
 if TYPE_CHECKING:  # pragma: no cover - import cycle guard, runtime import is lazy
     from ponte.daemon import TunnelDaemon
@@ -743,7 +743,7 @@ def serve(
             raise
         except Exception as exc:
             _fail(str(exc))
-        provider: Callable[[], dict] = DemoStatus()
+        provider: Provider = DemoStatus()
     else:
         try:
             daemon = _daemon()
@@ -758,8 +758,12 @@ def serve(
         except Exception as exc:
             _fail(str(exc))
 
-        def live_status() -> dict:
-            """每次请求都重新取一次真实状态（接口本身从不缓存）。"""
+        def live_status(_query: Mapping[str, list[str]]) -> dict:
+            """每次请求都重新取一次真实状态（接口本身从不缓存）。
+
+            ``?at=`` 是演示模式的事（演示时间轴是"某个时刻的纯函数"，所以能被钉在某一刻）。
+            真实状态只有"现在"，所以这里明确忽略查询串——不是忘了处理。
+            """
             return _status_payload(daemon.status())
 
         provider = live_status
diff --git a/ponte/serve.py b/ponte/serve.py
index 4ecc494..93b6572 100644
--- a/ponte/serve.py
+++ b/ponte/serve.py
@@ -29,7 +29,10 @@
 * **Read-only, and always fresh.** Every request re-reads the daemon status, so
   a page can never show a cached "healthy" for a tunnel that has since died.
   Nothing here can start, stop or reconfigure anything — the worst a leaked
-  token buys is a read of your port numbers.
+  token buys is a read of your port numbers. Even the demo clock obeys this: it
+  is pinned with a ``?at=`` query (see :mod:`ponte.demo`) rather than by poking
+  the server into a mode, so there is no state to race with, no non-idempotent
+  endpoint to guard, and two viewers of the same URL see the same board.
 
 The one thing this module deliberately does *not* do is invent numbers: the
 dashboard, the JSON, the health probe and the metrics are all rendered from the
@@ -57,6 +60,7 @@
 
 __all__ = [
     "PonteHTTPServer",
+    "Provider",
     "create_server",
     "dashboard_html",
     "health_response",
@@ -66,6 +70,16 @@
 
 logger = logging.getLogger(__name__)
 
+#: A status provider: one request's query string in, the payload to render out.
+#:
+#: The query is part of the contract because ``ponte serve --demo`` pins its
+#: timeline with ``?at=`` (:mod:`ponte.demo`). Handing the provider the request is
+#: what keeps that a *read* — the alternative, a control endpoint that mutates a
+#: clock, would put the first piece of mutable state, and the first
+#: non-idempotent route, into a server whose whole posture is "nothing here can
+#: change anything". A live daemon simply ignores the argument.
+Provider = Callable[[Mapping[str, list[str]]], dict[str, Any]]
+
 #: How many recent retry-loop events a dashboard card shows.
 _FEED_LIMIT = 8
 
@@ -753,6 +767,16 @@ def add(
   cursor: pointer;
 }
 button.pause:hover { color: var(--text); border-color: var(--accent); }
+/* The demo clock (`ponte serve --demo`). The reading is plain text so it works
+   without scripting; the buttons are hidden until the script that drives them
+   is running, because a dead control is worse than no control. */
+.democtl { display: inline-flex; align-items: center; gap: 6px 8px; flex-wrap: wrap; }
+.democtl b { color: var(--dim); font-weight: 600; font-variant-numeric: tabular-nums; }
+/* Frozen is a *state*, so it is coloured instead of only worded: a screenshot
+   of a paused clock should say so without anyone reading the label. */
+.democtl.frozen b { color: var(--unk); }
+#demobuttons { display: inline-flex; gap: 6px; }
+#demobuttons[hidden] { display: none; }
 .muted { color: var(--faint); }
 /* Narrow screens: stack the row instead of scrolling sideways. */
 @media (max-width: 760px) {
@@ -783,11 +807,11 @@ def add(
 <main id="board">$board</main>
 <footer>
   <span class="live" id="live">每 $refresh 秒自动刷新（无脚本时整页刷新）</span>
-  <button class="pause" id="pauser" type="button" hidden>暂停</button>$demo_note
+  <button class="pause" id="pauser" type="button" hidden>暂停</button>$demo_controls$demo_note
   <span class="links">数据来自 ponte status 的同一份状态，点任意一行看明细 ·
-  <a href="/status.json">status.json</a> ·
-  <a href="/metrics">metrics</a> ·
-  <a href="/healthz">healthz</a></span>
+  <a href="/status.json$at_query">status.json</a> ·
+  <a href="/metrics$at_query">metrics</a> ·
+  <a href="/healthz$at_query">healthz</a></span>
 </footer>
 <script>
 /* Progressive enhancement, in one place and one direction: everything above is
@@ -809,6 +833,11 @@ def add(
   var timer = null;
   var failures = 0;
   var paused = false;
+  var demoCtl = document.getElementById('democtl');
+  var demoButtons = document.getElementById('demobuttons');
+  var demoRead = document.getElementById('demoat');
+  var demoState = document.getElementById('demostate');
+  var demoFreeze = document.getElementById('demofreeze');
 
   function clock() {
     function pad(value) { return (value < 10 ? '0' : '') + value; }
@@ -858,8 +887,85 @@ def add(
     if (timer === null) { timer = window.setInterval(refresh, every); }
   }
 
+  /* ---------------------------------------------------------------------
+     The demo clock.
+
+     A demo payload is a pure function of "how long since the server started",
+     so the only thing this page has to do is keep that number moving and put
+     it in the URL — the server then renders that same moment for anyone who
+     opens the same link. Freezing is therefore not a server state to race
+     with: it is simply this page no longer advancing the number. With no
+     `at=` in the URL the server follows the wall clock and none of this runs.
+     --------------------------------------------------------------------- */
+  var elapsed = 0;   // seconds since the server started, as this page counts them
+  var anchor = null; // null = follow the clock; a number = pinned to that moment
+  var frozen = false;
+  var ticked = 0;
+
+  function human(seconds) {
+    var whole = Math.max(0, Math.floor(seconds));
+    var hours = Math.floor(whole / 3600);
+    var minutes = Math.floor((whole % 3600) / 60);
+    return hours + 'h ' + minutes + 'm ' + (whole % 60) + 's';
+  }
+
+  /* The next visible change is the server's to know: it owns the timeline. It
+     rides along on the rendered control, so it is refreshed with the board. */
+  function demoNext() {
+    var value = demoCtl ? parseFloat(demoCtl.getAttribute('data-next-at')) : NaN;
+    return isFinite(value) ? value : null;
+  }
+
+  function url() {
+    var params = new URLSearchParams(window.location.search);
+    if (anchor === null) {
+      /* Back to live: drop the anchor entirely rather than pinning "now". */
+      if (!params.has('at')) { return window.location.pathname + window.location.search; }
+      params.delete('at');
+    } else {
+      params.set('at', anchor.toFixed(1));
+    }
+    var query = params.toString();
+    return window.location.pathname + (query ? '?' + query : '');
+  }
+
+  function advance() {
+    var now = Date.now();
+    var step = ticked ? (now - ticked) / 1000 : 0;
+    elapsed += step;
+    /* While frozen the reading stays put — including across a tab left hidden,
+       which is the one place a frozen value would otherwise creep forward. */
+    if (anchor !== null && !frozen) { anchor += step; }
+    ticked = now;
+  }
+
+  function paint() {
+    if (!demoCtl) { return; }
+    var moment = (anchor === null ? elapsed : anchor);
+    var who = demoCtl.getAttribute('data-next-profile') || '';
+    demoCtl.className = 'democtl' + (frozen ? ' frozen' : '');
+    if (demoRead) { demoRead.textContent = human(moment); }
+    if (demoState) {
+      var target = demoNext();
+      var tail = target === null ? '' : ' · 下一处变化 ' + (who ? who + ' ' : '') + human(target - moment) + '后';
+      if (target !== null && target < moment) {
+        tail = ' · 已经越过下一处变化';
+      }
+      demoState.textContent = '（' + (frozen ? '已冻结' : (anchor === null ? '实时' : '已固定')) + tail + '）';
+    }
+    if (demoFreeze) { demoFreeze.textContent = frozen ? '继续' : '冻结'; }
+  }
+
   function refresh() {
-    fetch(window.location.pathname + window.location.search, {cache: 'no-store'})
+    advance();
+    paint();
+    var target = url();
+    if (target !== window.location.pathname + window.location.search) {
+      /* The address bar is the anchor, so it has to say what we are asking for
+         — a link copied mid-flight therefore reproduces this exact moment. */
+      window.history.replaceState(null, '', target);
+    }
+    fetch(target, {cache: 'no-store'})
       .then(function (response) {
         if (response.ok) { return response.text(); }
         if (response.status === 401 || response.status === 403) { throw 'auth'; }
@@ -874,6 +980,14 @@ def add(
         board.innerHTML = nextBoard.innerHTML;
         summary.innerHTML = nextSummary.innerHTML;
         restore(before);
+        var nextDemo = next.getElementById('democtl');
+        if (demoCtl && nextDemo) {
+          demoCtl.setAttribute('data-at', nextDemo.getAttribute('data-at'));
+          demoCtl.setAttribute('data-anchored', nextDemo.getAttribute('data-anchored'));
+          demoCtl.setAttribute('data-next-at', nextDemo.getAttribute('data-next-at'));
+          demoCtl.setAttribute('data-next-profile', nextDemo.getAttribute('data-next-profile'));
+          paint();
+        }
         failures = 0;
         say('ok', '已更新 ' + clock() + ' · 每 $refresh 秒');
       })
@@ -902,6 +1016,56 @@ def add(
       }
     });
   }
+  if (demoCtl) {
+    var rendered = parseFloat(demoCtl.getAttribute('data-at'));
+    elapsed = isFinite(rendered) ? rendered : 0;
+    if (demoCtl.getAttribute('data-anchored') === '1') { anchor = elapsed; }
+    ticked = Date.now();
+    paint();
+  }
+  /* The buttons are revealed here rather than in the markup: they only exist
+     once the code behind them does. */
+  if (demoCtl && demoButtons) {
+    demoButtons.hidden = false;
+    function pin(seconds) {
+      if (anchor === null) { anchor = elapsed; }  // 从"现在"起跳
+      anchor = Math.max(0, anchor + seconds);
+      ticked = Date.now();
+      refresh();
+    }
+    function wire(id, handler) {
+      var node = document.getElementById(id);
+      if (node) { node.addEventListener('click', handler); }
+    }
+    if (demoFreeze) {
+      demoFreeze.addEventListener('click', function () {
+        /* Deliberately does not move the anchor: freezing is "stop advancing",
+           so resuming continues from exactly where it stopped. Stepping while
+           frozen is the useful way to walk a fault state by state, so the step
+           buttons leave this alone. */
+        frozen = !frozen;
+        ticked = Date.now();
+        refresh();
+      });
+    }
+    wire('demoback', function () { pin(-10); });
+    wire('demofwd', function () { pin(10); });
+    wire('demonext', function () {
+      var target = demoNext();
+      if (target === null) { return; }
+      /* Just past the boundary, so what renders is the state *after* the
+         change — landing on it exactly would depend on float exactness. */
+      anchor = target + 0.05;
+      ticked = Date.now();
+      refresh();
+    });
+    wire('demolive', function () {
+      anchor = null;
+      frozen = false;
+      ticked = Date.now();
+      refresh();
+    });
+  }
   /* No point polling a tab nobody is looking at. */
   document.addEventListener('visibilitychange', function () {
     if (document.hidden) { stop(); }
@@ -1075,6 +1239,81 @@ def _feed(section: Mapping[str, Any]) -> str:
     return "".join(lines)
 
 
+def _demo_clock(payload: Mapping[str, Any]) -> tuple[float, bool, float | None, str] | None:
+    """Read the demo clock out of a payload: (时刻, 是否被钉住, 下一处变化, 哪条隧道)。
+
+    形状不对就当作"不是演示时钟"：标记决定这份数据是不是演示，而一个存在但畸形的标记
+    不该被当成实时基础设施（宁可什么都不说，也不要说得像真的）。
+    """
+    demo = payload.get("demo")
+    if not isinstance(demo, Mapping):
+        return None
+    at = _as_float(demo.get("at"))
+    if at is None:
+        return None
+    who = demo.get("next_profile")
+    return (
+        at,
+        bool(demo.get("anchored")),
+        _as_float(demo.get("next_at")),
+        who if isinstance(who, str) else "",
+    )
+
+
+def _demo_controls(payload: Mapping[str, Any]) -> str:
+    """The demo clock: which moment the board is showing, and the buttons that move it.
+
+    Rendered complete on the server, reading included, so a page with scripting off
+    still says which moment it is pinned to; the buttons appear only once the script
+    that implements them is running, because a dead control is worse than none.
+
+    The moment is also on the element as ``data-at``, and the *next* visible change
+    as ``data-next-at`` — that one is computed here, since only the server owns the
+    timeline (见 :func:`ponte.demo._next_change_at`).
+    """
+    clock = _demo_clock(payload)
+    if clock is None:
+        return ""
+    at, anchored, next_at, who = clock
+    if next_at is None:  # pragma: no cover - 演示时间轴总会有下一处变化
+        tail = ""
+    else:
+        # 哪条隧道变、还有多久——按钮只会说"下一处变化"，不说清是哪里的话，用户不知道该往
+        # 哪儿看（而看板上有三行）。
+        tail = f" · 下一处变化 {who + ' ' if who else ''}{_format_duration(max(0.0, next_at - at))}后"
+    next_attr = "" if next_at is None else f"{next_at:.1f}"
+    mode = "已固定" if anchored else "实时"
+    return (
+        f'\n  <span class="democtl" id="democtl" data-at="{at:.1f}"'
+        f' data-anchored="{1 if anchored else 0}" data-next-at="{next_attr}"'
+        f' data-next-profile="{_esc(who)}">'
+        f'<span class="muted">演示时钟 <b id="demoat">{_format_duration(at)}</b>'
+        f'<span id="demostate">（{mode}{tail}）</span></span>'
+        '<span id="demobuttons" hidden>'
+        '<button class="pause" id="demofreeze" type="button">冻结</button>'
+        '<button class="pause" id="demoback" type="button" title="回退 10 秒">−10s</button>'
+        '<button class="pause" id="demofwd" type="button" title="前进 10 秒">+10s</button>'
+        '<button class="pause" id="demonext" type="button"'
+        ' title="跳到下一处看得见的变化">下一处变化</button>'
+        '<button class="pause" id="demolive" type="button" title="去掉锚点，跟随实时">'
+        "回到现在</button>"
+        "</span></span>"
+    )
+
+
+def _at_query(payload: Mapping[str, Any]) -> str:
+    """Put the demo anchor on the footer's links.
+
+    Otherwise a board pinned at 2m32s hands out a ``status.json`` of *now*: the page
+    and the JSON describing two different moments is exactly the kind of disagreement
+    this module exists to avoid. Live demo data has no anchor to carry.
+    """
+    clock = _demo_clock(payload)
+    if clock is None or not clock[1]:
+        return ""
+    return f"?at={clock[0]:.1f}"
+
+
 def _demo_note(payload: Mapping[str, Any]) -> str:
     """Footer line for ``ponte serve --demo``: says where the data came from, in words."""
     if not payload.get("demo"):
@@ -1348,7 +1587,9 @@ def dashboard_html(
         title="隧道看板",
         summary=_summary(payload, profiles),
         board=board,
+        demo_controls=_demo_controls(payload),
         demo_note=_demo_note(payload),
+        at_query=_at_query(payload),
     )
 
 
@@ -1385,7 +1626,7 @@ class PonteHTTPServer(ThreadingHTTPServer):
     def __init__(
         self,
         address: tuple[str, int],
-        provider: Callable[[], dict[str, Any]],
+        provider: Provider,
         *,
         token: str = "",
         refresh: int = 5,
@@ -1482,6 +1723,7 @@ def _respond(self, *, head: bool) -> None:
         """Route one request: 404 → 401 → the endpoint."""
         parsed = urlparse(self.path)
         path = parsed.path.rstrip("/") or "/"
+        query = parse_qs(parsed.query)
         if path not in _ROUTES:
             self._send_json(
                 404,
@@ -1489,7 +1731,7 @@ def _respond(self, *, head: bool) -> None:
                 head=head,
             )
             return
-        if not self._authorized(parse_qs(parsed.query)):
+        if not self._authorized(query):
             self._send_json(
                 401,
                 {"error": "unauthorized: missing or invalid token"},
@@ -1499,7 +1741,7 @@ def _respond(self, *, head: bool) -> None:
             return
 
         try:
-            payload = self._state.provider()
+            payload = self._state.provider(query)
         except Exception as exc:  # noqa: BLE001 - answer, never drop the client
             logger.exception("serve: status provider failed")
             self._send_json(
@@ -1605,7 +1847,7 @@ def _send_text(
 
 
 def create_server(
-    provider: Callable[[], dict[str, Any]],
+    provider: Provider,
     *,
     host: str = "127.0.0.1",
     port: int = 8787,
diff --git a/tests/test_demo.py b/tests/test_demo.py
index 4362291..a70487b 100644
--- a/tests/test_demo.py
+++ b/tests/test_demo.py
@@ -8,11 +8,13 @@
 from __future__ import annotations
 
 import os
+import types
 
 import pytest
 from typer.testing import CliRunner
 
 from ponte import demo
+from ponte.config import ServeConfig
 from ponte.daemon import DaemonStatus, ProfileStatus
 from ponte.main import _status_payload, app
 from ponte.serve import dashboard_html, health_response, render_metrics
@@ -179,7 +181,14 @@ def test_payload_matches_the_status_json_contract_exactly() -> None:
     assert set(real) - set(demo_payload) == set()
     assert set(demo_payload["profiles"]["web"]) == set(real["profiles"]["web"])
 
-    assert demo_payload["demo"] is True
+    # 演示时钟仍然挤在同一个键里（而不是新开一个键），所以这份比对没变松。
+    assert set(demo_payload["demo"]) == {
+        "at",
+        "anchored",
+        "next_at",
+        "next_profile",
+        "next_state",
+    }
     assert set(demo_payload["profiles"]) == {"web", "db", "metrics"}
 
 
@@ -190,7 +199,7 @@ def test_demo_data_is_labelled_in_the_payload_and_on_the_page() -> None:
     拓扑图，所以它自己得说清楚这不是。
     """
     payload = _payload(152.0)
-    assert payload["demo"] is True
+    assert payload["demo"]["anchored"] is False, "没被 ?at= 钉住时要说实话"
     assert payload["pid"] == os.getpid(), "演示的\"守护进程\"就是提供页面的这个进程"
     assert payload["running"] is True
     assert payload["uptime_seconds"] == pytest.approx(152.0)
@@ -226,6 +235,164 @@ def test_same_moment_always_renders_the_same_payload() -> None:
     assert provider.payload(now=_START + 1.0) != provider.payload(now=_START + 152.0)
 
 
+# ---------------------------------------------------------------------------
+# 演示时钟：?at= 锚点与“下一处变化”
+# ---------------------------------------------------------------------------
+
+
+def _pinned(seconds: float) -> dict:
+    """``?at=`` 钉住的那一刻（页面据此要说“已固定”而不是“实时”）。"""
+    return demo.DemoStatus(started_at=_START)({"at": [str(seconds)]})
+
+
+def _visible(payload: dict) -> tuple:
+    """**看板上看得见的东西**：判定 / 结论是否确定 / 进程在不在 / 两列端口。
+
+    这里刻意不调 demo 自己的私有函数——那会把测试变成镜像（两处一起错还互不告白）。这是
+    拿渲染给用户看的那一层重算一遍。
+    """
+    return tuple(
+        (
+            name,
+            section["healthy"],
+            section["health_conclusive"],
+            section["process_alive"],
+            tuple(sorted(section["remote_ports"].items())),
+            tuple(sorted(section["local_ports"].items())),
+        )
+        for name, section in sorted(payload["profiles"].items())
+    )
+
+
+def test_the_clock_can_be_pinned_to_a_moment_by_the_query() -> None:
+    """``?at=<秒>`` 把这一刻钉在时间轴上——是**读**，不是控制端点。
+
+    锚点走查询串而不是服务端状态，这条测试把它钉住：同一个 provider 实例、同一个
+    ``?at=145``，两次调用给出同一份“断线中”的 payload，而 provider 自己没有变过。
+    """
+    provider = demo.DemoStatus(started_at=_START)
+
+    pinned = provider({"at": ["145"]})
+    assert pinned["uptime_seconds"] == pytest.approx(145.0)
+    assert pinned["demo"]["anchored"] is True
+    assert pinned["profiles"]["web"]["healthy"] is False
+    assert pinned["profiles"]["web"]["last_disconnect_reason"]
+    # 同一个锚点再问一次还是那一份：没有可变状态可以跑掉。
+    assert provider({"at": ["145"]}) == pinned
+
+    # 没有锚点就是实时，而且 ``anchored`` 如实说是 False。
+    live = provider({})
+    assert live["demo"]["anchored"] is False
+    assert live["uptime_seconds"] != pytest.approx(145.0)
+
+
+def test_the_anchor_renders_exactly_what_that_moment_renders_without_one() -> None:
+    """``?at=T`` 与 ``now=start+T`` 必须是同一份数据。
+
+    否则按钮与地址栏会各说各话：页面上的时刻与它声称的时刻不是一回事，而“一个 URL 就能
+    把看板固定在某一刻”也跟着失效。
+    """
+    provider = demo.DemoStatus(started_at=_START)
+    for seconds in (0.0, 25.0, 140.0, 146.0, 152.0, 170.0, 175.0, 210.0, 500.0):
+        pinned = provider({"at": [str(seconds)]})
+        direct = provider.payload(now=_START + seconds)
+        assert pinned["profiles"] == direct["profiles"], seconds
+        assert pinned["uptime_seconds"] == pytest.approx(direct["uptime_seconds"])
+
+
+@pytest.mark.parametrize("raw", ["", "abc", "-1", "nan", "inf", "-inf", "1e400", "0x10", "12s"])
+def test_a_bad_anchor_falls_back_to_live_instead_of_failing(raw: str) -> None:
+    """地址栏里的锚点可能是手改的、转发的、被别的工具弄坏的，所以坏值一律回退到实时。
+
+    回退而不是报错：这是只读的演示接口，一个参数打错不该让页面白屏；而回退的方向是“显示
+    实时数据”——看板仍然完整可用，只是没被钉住。
+    """
+    payload = demo.DemoStatus(started_at=_START)({"at": [raw]})
+    assert payload["demo"]["anchored"] is False
+    assert payload["demo"]["at"] == pytest.approx(payload["uptime_seconds"], abs=0.5)
+
+
+def test_an_absurd_anchor_is_clamped() -> None:
+    """``?at=999999999`` 被钳到一天，而不是让时间轴跑到几百万个循环之外。"""
+    payload = demo.DemoStatus(started_at=_START)({"at": ["999999999"]})
+    assert payload["demo"]["anchored"] is True
+    assert payload["uptime_seconds"] == pytest.approx(demo._AT_LIMIT)
+
+
+def test_the_next_change_is_the_earliest_one_that_actually_changes_something() -> None:
+    """``next_at`` 必须是“看得见的东西变了”的最近一刻。
+
+    两件事一起验，而且都是拿**渲染给看板的那一层**重算的：
+
+    * 在 ``next_at`` 之前，任何时刻的看板都与现在一模一样——否则按钮会跳过一段真的变化；
+    * 到 ``next_at`` 那一刻，看板确实不同了——否则按钮看上去像是没反应。
+
+    ``web`` 的“断线 → 重连退避”就是必须被跳过的例子：两段的判定与两列端口完全一样。
+    """
+    provider = demo.DemoStatus(started_at=_START)
+    for seconds in (0.0, 10.0, 30.0, 120.0, 145.0, 146.0, 152.0, 170.0, 175.0, 250.0, 400.0):
+        before = _visible(provider({"at": [str(seconds)]}))
+        next_at = provider({"at": [str(seconds)]})["demo"]["next_at"]
+        assert next_at is not None and next_at > seconds, seconds
+        probe = seconds
+        while probe + 0.5 < next_at:
+            probe += 0.5
+            assert _visible(provider({"at": [str(probe)]})) == before, (seconds, probe)
+        assert _visible(provider({"at": [str(next_at)]})) != before, seconds
+
+
+def test_the_next_change_names_the_tunnel_that_changes() -> None:
+    """按钮上写着“下一处变化”，就得知道是哪条隧道变了——否则用户不知道往哪儿看。"""
+    payload = _pinned(10.0)
+    assert payload["demo"]["next_profile"] == "db"
+    assert payload["demo"]["next_state"] == demo.DISCONNECTED
+    assert payload["demo"]["next_at"] == pytest.approx(25.0)
+
+
+def test_the_page_offers_the_clock_only_for_demo_data() -> None:
+    """控制条只在演示模式出现，而且“下一处变化”是服务端算的（它才知道时间轴）。
+
+    同时钉住一件事：**读数是纯文本**，所以关掉脚本的页面仍然说得出自己停在哪一刻；而按钮
+    与它背后的脚本一起出现（一个按下去没反应的控件比没有控件更糟）。
+    """
+    pinned = dashboard_html(_pinned(145.0), refresh=5, now=_START + 145.0)
+    assert 'id="democtl"' in pinned
+    assert 'data-at="145.0"' in pinned
+    assert 'data-anchored="1"' in pinned
+    assert 'data-next-at="164.0"' in pinned
+    assert 'data-next-profile="web"' in pinned, "按钮要说清是哪条隧道要变（看板上有三行）"
+    assert "web" in pinned.split("下一处变化")[1][:40]
+    assert "已固定" in pinned
+    assert "0h 2m 25s" in pinned, "读数得是给人看的时长"
+    assert 'id="demobuttons" hidden' in pinned, "按钮先藏着，等驱动它们的脚本起来"
+    # 锚点也跟着进页脚的链接，否则看板钉在某一刻、status.json 却回答"现在"。
+    assert 'href="/status.json?at=145.0"' in pinned
+
+    # 实时（没被钉住）时不该在链接上塞 at，也不该说"已固定"。
+    live = dashboard_html(_payload(10.0), refresh=5, now=_START + 10.0)
+    assert 'id="democtl"' in live
+    assert "实时" in live
+    assert 'href="/status.json"' in live
+    assert 'href="/status.json?at=' not in live
+    assert 'href="/metrics?at=' not in live
+
+    # 真实数据里根本没有这整个东西。
+    real = _status_payload(
+        DaemonStatus(
+            running=True,
+            pid=4242,
+            started_at=_START,
+            uptime_seconds=3600.0,
+            profiles=[ProfileStatus(name="web", destination="deploy@edge.example.com:22")],
+        )
+    )
+    real_html = dashboard_html(real, refresh=5, now=_START + 3600.0)
+    # 样式表是所有页面共用的，所以查**标记**而不是类名。
+    assert 'id="democtl"' not in real_html
+    assert "演示时钟" not in real_html
+    assert "演示数据" not in real_html
+
+
 # ---------------------------------------------------------------------------
 # 命令接线：--demo 不读配置、不碰守护进程，但绑定校验照旧
 # ---------------------------------------------------------------------------
@@ -271,8 +438,8 @@ def fake_create_server(provider, **kwargs):
         "token": "",
         "refresh": 5,
     }
-    payload = captured["provider"]()
-    assert payload["demo"] is True
+    payload = captured["provider"]({})
+    assert payload["demo"]["anchored"] is False
     assert set(payload["profiles"]) == {"web", "db", "metrics"}
 
 
@@ -285,3 +452,48 @@ def test_demo_mode_still_refuses_to_expose_the_dashboard_without_a_token(monkeyp
     result = CliRunner().invoke(app, ["serve", "--demo", "--host", "0.0.0.0"])
     assert result.exit_code != 0
     assert "令牌" in result.output
+
+
+def test_live_mode_ignores_the_demo_anchor(monkeypatch) -> None:
+    """``?at=`` 只属于演示模式：真实状态只有“现在”，非演示模式下它必须什么都不做。
+
+    这条钉的是一个**不该开的后门**。如果实时路径也认这个参数，那么任何能访问到这个端口
+    的人（或者一个把地址栏填好的链接）就能让看板显示一个“过去/未来的”状态——而真实状态
+    根本没有其它时刻可言，时间轴只存在于演示数据里。
+    """
+
+    class _Daemon:
+        config = types.SimpleNamespace(serve=ServeConfig())
+
+        def status(self) -> DaemonStatus:
+            return DaemonStatus(
+                running=True,
+                pid=4242,
+                started_at=_START,
+                uptime_seconds=42.0,
+                profiles=[
+                    ProfileStatus(name="web", destination="deploy@edge.example.com:22")
+                ],
+            )
+
+    monkeypatch.setattr("ponte.main._daemon", _Daemon)
+    captured: dict = {}
+
+    class _Server:
+        def serve_forever(self, poll_interval: float = 0.5) -> None:
+            raise KeyboardInterrupt
+
+        def server_close(self) -> None:
+            pass
+
+    def fake_create_server(provider, **kwargs):
+        captured["provider"] = provider
+        return _Server()
+
+    monkeypatch.setattr("ponte.main.create_server", fake_create_server)
+    result = CliRunner().invoke(app, ["serve", "--port", "8792"])
+    assert result.exit_code == 0, result.output
+
+    payload = captured["provider"]({"at": ["999"]})
+    assert "demo" not in payload
+    assert payload["uptime_seconds"] == pytest.approx(42.0), "实时状态不许被锚点挪动"
diff --git a/tests/test_integration_serve.py b/tests/test_integration_serve.py
index 960bd76..31d0c4f 100644
--- a/tests/test_integration_serve.py
+++ b/tests/test_integration_serve.py
@@ -92,7 +92,7 @@ def _daemon_with_snapshot(tmp_path: Path, probe: object) -> TunnelDaemon:
 
 def _start(daemon: TunnelDaemon, token: str = "s3cret"):
     server = create_server(
-        lambda: _status_payload(daemon.status()),
+        lambda _query: _status_payload(daemon.status()),
         host="127.0.0.1",
         port=_free_port(),
         token=token,
diff --git a/tests/test_main.py b/tests/test_main.py
index 209d1e9..6c9353a 100644
--- a/tests/test_main.py
+++ b/tests/test_main.py
@@ -817,7 +817,7 @@ def test_serve_command_serves_and_stops_cleanly(monkeypatch) -> None:
     assert record["server"].closed is True
     assert record["server"].kwargs["port"] == 9100
     # provider 必须现读现取：看板的“新鲜度”全靠它，缓存一次就失去意义。
-    payload = record["provider"]()
+    payload = record["provider"]({})
     assert payload["profiles"]["default"]["healthy"] is True
 
 
diff --git a/tests/test_serve.py b/tests/test_serve.py
index eb1acdb..c03e800 100644
--- a/tests/test_serve.py
+++ b/tests/test_serve.py
@@ -685,7 +685,7 @@ def test_request_lines_cannot_forge_log_lines(caplog) -> None:
     """
     hostile = b"GET /x\x1b[31mFORGED\x00\x7f\xc2\x80 HTTP/1.1"
     with caplog.at_level(logging.DEBUG, logger="ponte.serve"):
-        with _running_server(lambda: _payload()) as base:
+        with _running_server(lambda _query: _payload()) as base:
             _raw_request(base, hostile)
 
     logged = [record.getMessage() for record in caplog.records if record.name == "ponte.serve"]
@@ -695,7 +695,7 @@ def test_request_lines_cannot_forge_log_lines(caplog) -> None:
 
 
 def test_end_to_end_endpoints_answer() -> None:
-    with _running_server(lambda: _payload()) as base:
+    with _running_server(lambda _query: _payload()) as base:
         status, headers, body = _get(base + "/")
         assert status == 200
         assert headers["Content-Type"].startswith("text/html")
@@ -718,7 +718,7 @@ def test_end_to_end_endpoints_answer() -> None:
 def test_end_to_end_healthz_tracks_the_tunnel() -> None:
     """The probe reports the tunnel, not the process: 503 when it breaks."""
     state = {"payload": _payload()}
-    with _running_server(lambda: state["payload"]) as base:
+    with _running_server(lambda _query: state["payload"]) as base:
         assert _get(base + "/healthz")[0] == 200
         state["payload"] = _payload(
             profiles={"web": _profile(healthy=False, health_error="port closed")}
@@ -731,7 +731,7 @@ def test_end_to_end_healthz_tracks_the_tunnel() -> None:
 def test_end_to_end_status_is_never_cached() -> None:
     """A replayed "healthy" page is the exact failure the endpoint prevents."""
     state = {"payload": _payload()}
-    with _running_server(lambda: state["payload"]) as base:
+    with _running_server(lambda _query: state["payload"]) as base:
         _, headers, _ = _get(base + "/")
         assert headers["Cache-Control"] == "no-store"
         state["payload"] = {"running": False}
@@ -739,7 +739,7 @@ def test_end_to_end_status_is_never_cached() -> None:
 
 
 def test_end_to_end_unknown_path_and_method() -> None:
-    with _running_server(lambda: _payload()) as base:
+    with _running_server(lambda _query: _payload()) as base:
         status, _, body = _get(base + "/nope")
         assert status == 404
         assert "/metrics" in json.loads(body)["endpoints"]
@@ -751,7 +751,7 @@ def test_end_to_end_unknown_path_and_method() -> None:
 
 
 def test_end_to_end_head_sends_headers_without_a_body() -> None:
-    with _running_server(lambda: _payload()) as base:
+    with _running_server(lambda _query: _payload()) as base:
         status, headers, body = _get(base + "/metrics", method="HEAD")
         assert status == 200
         assert int(headers["Content-Length"]) > 0
@@ -760,7 +760,7 @@ def test_end_to_end_head_sends_headers_without_a_body() -> None:
 
 def test_end_to_end_token_gate() -> None:
     """With a token set, nothing is served without it — header or query."""
-    with _running_server(lambda: _payload(), token="s3cret") as base:
+    with _running_server(lambda _query: _payload(), token="s3cret") as base:
         for path in _ROUTES_FOR_TOKEN_TEST:
             status, headers, _ = _get(base + path)
             assert status == 401, path
@@ -792,7 +792,7 @@ def broken() -> dict:
 def test_serve_refuses_to_expose_without_a_token() -> None:
     """Refusing beats warning: the page maps your infrastructure."""
     with pytest.raises(ConfigValidationError) as caught:
-        create_server(lambda: _payload(), host="0.0.0.0", port=0)
+        create_server(lambda _query: _payload(), host="0.0.0.0", port=0)
     assert "token" in str(caught.value)
 
 
@@ -810,7 +810,7 @@ def test_serve_allows_a_non_loopback_bind_when_a_token_is_set() -> None:
 
 def test_create_server_carries_its_settings() -> None:
     server = create_server(
-        lambda: _payload(), host="127.0.0.1", port=0, token="s3cret", refresh=9
+        lambda _query: _payload(), host="127.0.0.1", port=0, token="s3cret", refresh=9
     )
     try:
         assert server.token == "s3cret"
@@ -819,6 +819,28 @@ def test_create_server_carries_its_settings() -> None:
         server.server_close()
 
 
+def test_the_provider_sees_this_request_s_query() -> None:
+    """provider 拿到的是**这一次请求**的查询串（演示时钟的锚点走的就是这条路）。
+
+    值得单独钉住，因为这不只是个实现细节：``ponte serve --demo`` 靠它把时间轴钉在
+    ``?at=`` 上，而那就是“服务端不必持有可变状态”的前提。哪天这层接线被静默改掉，演示
+    时钟会退化成“按钮不起作用”，而其它测试全是绿的。
+    """
+    seen: list[dict[str, list[str]]] = []
+
+    def provider(query):
+        seen.append({key: list(value) for key, value in query.items()})
+        return _payload()
+
+    with _running_server(provider) as base:
+        status, _, _ = _get(f"{base}/status.json?at=145&token=x")
+        assert status == 200
+
+    assert seen, "provider 应该被调用过"
+    assert seen[-1].get("at") == ["145"]
+    assert seen[-1].get("token") == ["x"]
+
+
 @pytest.mark.parametrize(
     ("host", "expected"),
     [