Echo Dashboard

Status: Design + partial ship (PR-A.A shipped 2026-04-26: page shell + retention-paused list + Scan / Re-enable; typed-confirmation Purge shipped 2026-07-01 — dashboard fragment + POST /api/v1/echo/retention-paused/purge, §3.4; persistence still deferred. PR-H shipped 2026-06-18: process tree viewer, as-built §5 — local-Echo-data-only. See docs/roadmap.md Phase 15.) Audience: Server engineers, dashboard UI engineers, Echo plugin maintainers Owners: architect (page architecture), plugin-developer (Echo action surface), security-guardian (SQL execution surface), docs-writer (DSL + REST docs) Related: docs/scope-walking-design.md (the cross-cutting result-set primitive this page consumes), docs/yuzu-guardian-design-v1.1.md (the agent tamper-resistance pillar that the process tree viewer’s data quality depends on), agents/plugins/echo/ (the data plane).

1. Why a dedicated Echo page

The Echo plugin is one of the highest-leverage operator surfaces in Yuzu — it answers the “what happened on this machine” question that drives forensics, compliance, and reactive IR. Today it is reachable only via the generic instruction-launch flow and the /fragments/echo-sql HTMX fragment embedded in another page; the surface area is large but the affordances are scattered. Operators repeatedly asked “where do I go to do Echo” — the answer needs to be a single dashboard page.

The page is also the home for several affordances that did not have anywhere to live:

1. Retention-paused source list — the operator-facing view of <source>_enabled=false per device, born from issue #539. Without it, an operator who disabled process_enabled on a device for forensic preservation has no aggregate view of which boxes are accumulating non-aging data.
2. Process tree viewer — reconstructed per-host from that host’s local Echo warehouse ($Process_Live + $TCP_Live) only, with no seed (as-built; see §5). Forensic timeline of every process born under a parent over a chosen window, with an honest “no-seed” completeness caveat (Windows is names-only). The pane also embeds device-level DNS-cache + ARP-table panels (ADR-0015) — dispatched read-only echo.sql over $DNS_Live/$ARP_Live to the selected host, rendered beside the tree. These are device views, not per-process (the DNS cache carries no pid); they audit echo.dns.read / echo.arp.read (DNS is usage-class PII, separately countable).
3. Capture sources frame (ADR-0015) — a per-device toggle table for the eleven core sources (process, tcp, service, user, perf, procperf, netqual, module, arp, dns, registry; the rest are toggled through echo.configure), with a category filter (six chips: Processes, Network, Services, User sessions, Performance and, for registry, System; the registry row also carries a NEW badge) and a staged-then-push guardrail: toggling a source only stages the change; nothing is dispatched until the operator clicks Push (guards against an accidental toggle of a usage-class source in either direction). Reads echo status + echo compatibility; Push dispatches echo configure <source>_enabled per change (audited echo.sources.read / echo.sources.configure). The same configure path is reachable via MCP/REST crossplatform.echo.configure.

The page is also the surface where scope walking (per docs/scope-walking-design.md) becomes most visibly useful — the Echo SQL query is the canonical iterative-narrowing tool (it now starts from the Result sets page, From Echo query, rather than from a frame on /echo), and result-set chips are the operator’s reasoning chain made visible.

2. Information architecture

 Dashboard ──────────────────────────────────────────────────────────────────
 │
 ├─ Devices       (existing)
 ├─ Inventory     (existing)
 ├─ Instructions  (existing)
 ├─ Policies      (existing)
 ├─ Echo           (new — this page) ──────────────────────────────────────────┐
 │                                                                            │
 │  /echo                                                                      │
 │  ┌────────────────────────────────────────────────────────────────────┐    │
 │  │  [Scope chip ▼]  windows-chrome-suspects · 2,798 devices · pinned  │    │
 │  │  ─── lineage breadcrumb (per scope-walking §8.2) ────────────────  │    │
 │  └────────────────────────────────────────────────────────────────────┘    │
 │  ┌─ Retention-paused sources (PR-A) ──────────────────────────────────┐    │
 │  │   device              source     paused since   live rows  oldest  │    │
 │  │   prod-eu-1 (Linux)   process    2026-04-25      18,402   31d 4h   │    │
 │  │   prod-eu-1 (Linux)   tcp        2026-04-25       4,193   31d 4h   │    │
 │  │   ...                                                              │    │
 │  │   [Re-enable]  [Purge data]  [Export CSV]                          │    │
 │  └────────────────────────────────────────────────────────────────────┘    │
 │  ┌─ Echo SQL (PR-D, scope-walking-aware) ──────────────────────────────┐    │
 │  │   $Echo  > SELECT name, COUNT(*) FROM process_hourly GROUP BY name  │    │
 │  │   [Run scoped to: windows-chrome-suspects]                         │    │
 │  │                                                                    │    │
 │  │   results... (streamed)                                            │    │
 │  │   [Save as result set ▼ "chrome-procs"]                            │    │
 │  └────────────────────────────────────────────────────────────────────┘    │
 │  ┌─ Process tree viewer (PR-H) ───────────────────────────────────────┐    │
 │  │   device: [pick from scope ▼]                                      │    │
 │  │                                                                    │    │
 │  │   1   systemd                                                      │    │
 │  │   ├── 234   sshd                                                   │    │
 │  │   │   └── 1402  bash (user=alice)                                  │    │
 │  │   │       └── 1419  python3 train.py  ← still running              │    │
 │  │   ├── 412   docker                                                 │    │
 │  │   │   ├── 998   containerd                                         │    │
 │  │   │   └── ...                                                      │    │
 │  │   ├── 814   yuzu-agent  (★ self)                                   │    │
 │  │   ...                                                              │    │
 │  │   Tree as observed since 2026-04-12 09:14 UTC (agent install)      │    │
 │  └────────────────────────────────────────────────────────────────────┘    │
 │                                                                            │
 ├─ Settings      (existing)                                                  │
 └────────────────────────────────────────────────────────────────────────────┘

URL structure:

3. PR-A — Retention-paused source list

Goal: every device × source pair where <source>_enabled=false, surfaced in a sortable, filterable, exportable table, with one-click re-enable and an explicit “purge data” action gated behind a typed-hostname confirmation.

3.1 Data flow

The source of truth is the agent’s echo_config table — the <source>_enabled keys, set by the echo.configure action. The server does not currently maintain a centralised “Echo config” mirror; the data path is request-driven:

1. Page load fans out echo.status (extended in PR-A to emit the four <source>_enabled values + the <source>_live_rows count + <source>_oldest_ts per source) to every device the page’s scope resolves to. Scope is the active scope chip (default __all__ for fresh page load).
2. Responses stream back via the standard agent-streaming pipeline.
3. Server collates into a transient in-memory table; renders as HTMX OOB swaps.
4. Empty rows (enabled=true for all four sources) are dropped — the table only shows the paused state, not the entire fleet.

Tri-state enabled values + dedup (#560/#558/#561). The <source>_enabled value is read as a tri-state: true → dropped (collecting normally); false → normal paused row; any other value (errored from a corrupt/tampered agent DB, or garbage) → a value-error badge row showing the reported value (it is NOT silently dropped — that would hide a paused/broken source). A disabled source with paused_at == 0 (a pre-v0.12.0 agent) renders a “schema older than server” badge and sorts as the oldest (top), instead of a bare — sunk to the bottom. Both value-error and unknown-paused_at rows float to the top. Before parsing, responses are deduplicated to the most-recent per agent by the server-stamped received_at_ms (never the agent-claimed timestamp, which a compromised agent could backdate to hide its state) — bounding render cost to O(agents × sources) against a response-spam DoS. The complementary store-side per-(command_id, agent_id) cap is a tracked follow-up.

This avoids a new persistent server-side mirror, which would have to be reconciled with agent state on every config change. The trade-off is a 5-15s page-load cost on a large fleet; mitigated by:

• Scope-restricted queries (the operator usually narrows first via a result set)
• Manual Refresh button for ad-hoc re-fan-out (automatic background refresh is planned for Phase 15.G operational hardening)
• Manual “Refresh” button for ad-hoc re-fan-out

Bounded scan read (#4644). The scan’s response read goes through the byte-aware store fetch (10,000 rows / 50 MiB of response payload). A cut is reported, never silent: the page shows a “Partial result” banner, qualifies its header counts and, with no rows in the part that was read, replaces the “still in progress” / “all clear” empty states with one saying the page cannot tell; GET /api/v1/echo/retention-paused and list_echo_retention_paused carry result_truncated_by_cap: true and also set store_degraded: true. This page is a dispatch-and-poll view, not a capture source, so the CORE capture-source pattern (§8 of the implementer doc) does not apply.

3.2 Extending echo.status

The action’s response gains four lines per source (so 16 new lines total for the 4 sources):

config|process_enabled|true
config|process_live_rows|18402
config|process_oldest_ts|1730000000
config|process_paused_at|0           # 0 = never; otherwise the ts when last set to false
config|tcp_enabled|false
config|tcp_live_rows|4193
config|tcp_oldest_ts|1733000000
config|tcp_paused_at|1735689600
...

config|<source>_paused_at|... is new — it requires the do_configure handler in echo_plugin.cpp to write this timestamp whenever it transitions a source from enabled to disabled (and clear it on the reverse). This is the operator-facing “paused since” column and is only meaningful at the server’s wall-clock. Backwards-compatible — if the field is absent, the dashboard renders — and falls back to “unknown.”

3.3 Re-enable action

Single-row “Re-enable” button → confirm modal → server dispatches echo.configure with the appropriate <source>_enabled=true to the named device. On success, the row drops out of the table on the next refresh; on failure the row turns yellow with the error tooltip.

Per-source independence (the #539 invariant) means re-enabling one source on a device does not touch the other three — the dispatched parameter is per-source.

3.4 Purge action

The “Purge data” button on a row is more dangerous than re-enable — it tells the agent to drop every row from <source>_live, <source>_hourly, <source>_daily, <source>_monthly for that source, without re-enabling the collector. The use case is “we paused process collection 8 weeks ago for forensic preservation; we have what we need, the disk is filling up, drop the rows but keep the collector paused.”

Server dispatches a new agent action echo.purge_source with {source: <name>}. The action is gated behind a typed-hostname confirmation (“type the device hostname to confirm purge of process data”), per the destructive-action discipline in the project root CLAUDE.md. Audit row: action: echo.source.purge, principal: <session>, result: success|failure, detail: device=<id> source=<name> — the dispatch audit row does not carry rows_deleted (see the as-shipped note below).

As shipped (Phase 15.A, 2026-07-01). Route POST /fragments/echo/retention-paused/purge; audit verb echo.source.purge (matching the echo.source.reenable sibling); metric yuzu_echo_source_purge_total{result}. The typed confirmation is a native prompt() (“type the device hostname”), not a bespoke modal — CSP-safe (no hx-on/eval), consistent with the native confirm() used for re-enable. The paused-guard is agent-side and authoritative: echo.purge_source refuses (source_not_paused) if the source is currently enabled, or (config_unreadable) if the enable flag cannot be read so the agent cannot confirm the source is paused (nothing is purged either way), which closes the scan→purge TOCTOU. The server does not enforce a SOURCE_NOT_PAUSED check (§3.5) because the retention-paused frame is an ephemeral live scan with no persisted paused-state to check. Dispatch is fire-and-forget, so rows_deleted is computed agent-side and returned in the response record — it is not in the immediate dispatch audit row.

A1 REST parity + generic-dispatch hardening (2026-07-01). Automation/MCP callers use the structured POST /api/v1/echo/retention-paused/purge (JSON body {device_id, source}, Infrastructure:Delete per-device-scoped, A4 error envelope, 202 + command_id; audited fail-closed — no dispatch without a durable audit row). Both the fragment and the REST route confirm the guard is agent-side authoritative. The generic POST /api/command escape hatch now also elevates destructive actions: echo.purge_source there additionally requires Infrastructure:Delete and is confined to the caller’s visible agents with untargeted broadcast/scope fan-out refused, so it can’t be a weaker path than the dedicated route. The atomic agent-side guard (check + delete under one lock) closes the agent-local check→delete race in addition to the scan→purge TOCTOU.

3.5 Permissions and safety

• View-only access requires Infrastructure:Read.
• Scan fleet requires Execution:Execute (it dispatches a fleet-wide command — same tier as run-instruction and echo-execute siblings).
• Re-enable requires Execution:Execute and the operator’s RBAC visibility on the target device. Out-of-scope device_id values collapse to the same 404 response as not-connected agents (no enumeration oracle); the audit log records the real reason server-side.
• Purge requires Infrastructure:Delete on the target device (a higher tier than re-enable’s Execution:Execute), plus the operator’s RBAC visibility on the device (same 404-collapse as re-enable). The paused-state guard is agent-side and authoritative: echo.purge_source refuses (source_not_paused) unless the source currently reports disabled, or (config_unreadable) when the enable flag cannot be read so the agent cannot confirm it (nothing is purged either way), which closes the scan→purge TOCTOU and prevents purging an actively-collecting source. The server does not enforce a SOURCE_NOT_PAUSED check — the retention-paused frame is an ephemeral live scan with no persisted paused-state to check, so the authoritative guard lives on the agent that owns the data (see §3.4). The agent action validates source against the full capture-source registry; the server route additionally restricts it to the four retention-frame sources {process, tcp, service, user}.

3.6 Tests

• Server-side: unit tests for the aggregation/render path against synthetic echo.status responses (paused-only, all-paused, none-paused, partial response).
• Agent-side: extends tests/unit/test_echo_aggregator.cpp (the suite added for #539) with a config-roundtrip test for <source>_paused_at write-on-disable / clear-on-enable.
• Integration: stand up the UAT stack, disable a source on a synthetic agent, confirm the row appears in the page within one refresh tick, click re-enable, confirm the row drops.

4. PR-D — Echo SQL frame, scope-walking-aware

As built: the frame was not kept on /echo. The Echo page carries a short note linking to Result sets, and the same query (parent scope, SQL, name, include-empty) is run from Result sets > From Echo query, behind a confirm that shows the SQL. The text below is the original design.

The frame body is largely the existing /fragments/echo-sql route (server/core/src/dashboard_routes.cpp:500). PR-D moves it onto the new page and wires it into the result-set primitive (docs/scope-walking-design.md):

1. Scope chip in the frame header — operator picks an active result set (or a standard scope) before submitting. The dispatch resolves from_result_set:<id> to the device-ID set per scope-walking-design.md §4.
2. “Save as result set” button on the results pane — after a query returns, operator clicks “Save as result set,” names it, and the server creates a new result set (source_kind=echo_query) with member IDs equal to the union of agents that returned ≥1 row. Default name is echo-<first-five-chars-of-sql-hash> so the operator can save without typing.
3. Lineage breadcrumb above the frame mirrors the active scope chip’s lineage (scope-walking-design.md §8.2).

No changes to the echo.sql agent action; the change is purely server-side scope resolution + result-set persistence.

5. PR-H — Process tree viewer (as-built)

Deviation from the original seed-based design below (kept for history). What shipped reconstructs the tree from the agent’s existing local Echo warehouse only ($Process_Live + $TCP_Live, queried via the read-only echo.sql action) — there is no agent-side seed action, no action='seed' rows, no __checkpoint__ rows, and (until #4027) no /api/v1/echo/process-tree REST surface at all. #4027 added GET /api/v1/echo/process-tree as the frame’s device-PICKER list twin only (§5.6) — the per-device reconstructed-tree JSON surface this paragraph is about remains deferred. This was a deliberate scope choice (local-Echo-data-only); the consequence is an honest completeness limit (see “Honesty” below). Modules: server engine server/core/src/echo_process_tree.{hpp,cpp} (pure, unit-tested), routes server/core/src/echo_tree_routes.{hpp,cpp}, page echo_page_ui.cpp Frame 3.

5.1 Reconstruction model (as-built)

• The viewer dispatches two canned, read-only echo.sql queries to ONE selected live host — SELECT … FROM $Process_Live and … FROM $TCP_Live — through the same dispatch-and-poll seam the device-page “Get live info” uses (untracked dispatch, execution_id="", so it never enters the executions drawer). The agent runs them on its read-only authorizer connection (#760/#631).
• The agent forbids recursive CTEs, so the tree is reconstructed server-side in C++ from the flat event rows: per-pid alive-intervals are built from the started/stopped stream, incarnations whose lifetime overlaps the chosen window [from, to] are kept (PID-reuse-safe — each lifetime is its own node), and each is linked to the parent incarnation that owned its ppid when it started. Orphans (parent not present / ppid 0 / start event aged out) become roots. Cycle- and 50k-node-cap guarded.
• Timescale controls. Preset chips — On boot · On agent install · Last minute · Last 10m · Last hour · Last day — plus a custom From/To (UTC) box. Point-in-time is the from == to case. to is the upper bound (running-vs-exited is decided at to); the SQL fetch lower bound stays oldest-retained so a long-running process started before the window still appears. On boot and On agent install are Echo-derived proxies (Echo has no boot/install-time column): install = MIN(ts) over retained rows; boot = the most-recent start of a root process (ppid==0), falling back to install.

Honesty in framing. Banner reads e.g. Window <from> → <to> · observed since <oldest-retained> · 411 nodes (281 running / 130 exited) · 0 flagged, with a note that — because there is no seed — a process whose started event has aged out of the 100k $Process_Live cap (or that predates the oldest retained row) may not appear, and that the boot/install anchors are proxies. On Windows the feeder is ETW (names-only) so per-process path and command line are blank (stated inline); they are populated on Linux/macOS.

5.2 Filtering, grouping, network (client-side display)

Reconstruction always returns the full tree; display filtering is client-side (instant, no re-dispatch — each row carries data-state/data-anom):

• State filter — All / Running / Exited chips.
• Anomalies only — toggle (the sole heuristic is a suspicious parent→child name-pair denylist, e.g. an office app or browser spawning a shell/LOLBin; flagged server-side, name-based so it works on Windows).
• Text filter — matches name / PID / remote IP.
• All three combine, reveal+expand the ancestor branches of matches, and are re-applied after every tree swap (htmx:afterSettle).
• Same-name grouping — 4+ identical-name siblings collapse into one name ×N (R running · E exited) row (e.g. svchost.exe ×106), expandable to the individual PIDs (each still drill-able). Filters auto-expand groups with matches.
• Inline network — each row shows its $TCP_Live connections joined by pid: a count + remote IP:port endpoints (public/routable egress highlighted amber; listeners shown as :port listen). Full connection table is in the detail panel.

5.3 Layout & detail panel

Two-column: a scrollable tree on the left and a sticky, always-visible detail panel on the right (stacks below on narrow viewports). Clicking any process row hx-gets /fragments/echo/process-tree/detail into the right panel — name, PID, parent PID, user, running/exited + start time, path + command line (blank-with-note on Windows), the process’s connections, and anomaly evidence. The detail renders from a server-side reconstruction cache (bounded LRU, 180 s TTL, keyed by a CSPRNG token — secure_random::random_hex, never mt19937) so row clicks need no further agent round-trip. The cache entry is bound to the operator who created it: detail fails closed unless the requesting session matches, so a predicted or leaked token can’t be replayed by a different operator (transparent to the normal same-session flow). If secure token generation fails (entropy exhaustion), result returns an in-panel error and caches nothing rather than minting a weak token.

5.4 Routes

5.5 Permissions & audit

• Viewing the frame: Infrastructure:Read.
• Reconstructing dispatches a live echo.sql, so run/result also require Execution:Execute and the per-device management scope (require_scoped_permission) — same posture as the Echo SQL frame and the device live-info probe. (This tightens the original “Infrastructure:Read to view” framing, which assumed a stored, non-dispatching tree.)
• detail holds the same tier as the reconstruction — it re-checks Infrastructure:Read and Execution:Execute scoped to the cached device, and binds to the originating principal. So a leaked/predicted token can neither cross management scope, downgrade the Execute tier (read behavioral detail an operator couldn’t reconstruct themselves), nor be replayed under a different session.
• $Process_Live.cmdline is already redaction-applied at capture by the agent, so no server-side re-redaction is needed; all agent-controlled fields are HTML-escaped.
• Agent output is byte-capped before parse (16 MiB process / 4 MiB TCP, defense in depth over the gRPC message bound); the echo.sql query interpolates only an int64 upper-bound timestamp (no string concat — see the load-bearing comment at the query site).
• Audit echo.process_tree.read fires twice (parity with device.live.*): a dispatch row when the live query is sent (recorded even if the device is offline or the poll never completes) and a success row after the tree renders; a failure row (csprng_unavailable) if secure token generation fails. The device is the target_id (not in detail); the success detail is preset=… from=… to=… nodes=… anomalies=… os=… conns=… (preset canonicalized to a fixed allowlist and os normalized to {windows,linux,macos,?} so neither can forge an audit field; conns=1 flags that per-process connection data was shown). Each detail drilldown emits an echo.process_tree.detail row (node=… os=…). See docs/user-manual/audit-log.md.

5.6 Deferred

• Agentic-first REST/MCP parity for the reconstruction itself — a JSON surface returning the PER-DEVICE reconstructed tree ({device_id} in the path, the /result+/detail fragments’ data) — remains deferred. #4027 (API-parity programme) shipped REST+MCP twins for the OTHER three Echo fragment reads — the process-tree and capture-sources device PICKER lists (GET /api/v1/echo/process-tree / GET /api/v1/echo/capture-sources, no {device_id} segment — distinct routes from the still-deferred one above, no path collision) and the retention-paused source list (GET /api/v1/echo/retention-paused) — plus MCP tools list_echo_process_tree_devices / list_echo_capture_sources_devices / list_echo_retention_paused. #4027 deliberately did NOT twin /fragments/echo/process-tree/result or .../detail — deferred as scope, not impossibility. /detail’s cache token is a CSPRNG value minted and principal-bound only inside the /result handler itself, so a /detail twin genuinely has no usable input today. /result’s pcmd/tcmd pair is an ordinary echo sql dispatch result (Infrastructure:Read, no execute gate) reachable in principle through the already-twinned generic dispatch surface (execute_instruction / POST /api/command) by reproducing the two canned $Process_Live/$TCP_Live queries verbatim — not a dedicated API path, and a real twin would still need a new async polling contract (no htmx auto-reissue on REST/MCP). Both are otherwise minted only by the dashboard-only /run route, itself excluded as dispatch-shaped (batched with #3994). Revisit once a /run (and /result) twin lands — see scripts/ci/api-parity/echo.json’s exception: rows on those two paths.
• Loaded modules / libraries — not shown by the viewer: the module source records image loads on Windows (ETW) into the $Module_* tables, which echo.sql reads.
• Seed snapshot (the original §5.1 below) — intentionally not built; revisit only if the no-seed completeness limit proves insufficient in the field.

5.7 Timeline renderers (building blocks, not yet wired)

server/core/src/echo_timeline_view.hpp defines the model of a per-device timeline read, and echo_timeline_render.{hpp,cpp} holds the pure renderers that turn it into the device bar, the “what is kept” chart, the lanes, the moment and selected panels and the “What this record cannot tell you” list. No page, route or API uses them yet, so nothing is operator-visible.

• What the model must say. Each lane covers its window with typed regions (exact, rolled-up, pruned, paused, not readable with a reason, capped with the point it reaches back to). A stretch with no region renders as “Coverage not stated”, never as exact. Offline, failed and too-old-agent reads render as not readable, never as empty.
• Retention. An expiry is stated only from the configured policy or a row limit. Measured coverage (the oldest row actually seen) is never turned into an expiry, and a source whose measurement could not be made says so instead of “Gone”.
• Wording follows the read. Polling interval, process capture method, operating system and unknown values change the wording; an unknown is worded as unknown, and DNS names are never tied to a process.
• Bounds and escaping. Output is bounded per lane and for the selected panel. Every dynamic value is HTML-escaped; links are supplied by the caller as server-built relative paths with ids percent-encoded, and no route path is fixed in the renderers.
• Time. Every stated time is UTC. Windows outside the years 1970 to 9999 are not drawn.

The data that fills the model (the read, its permissions, audit and the API twins) is separate work; this section records the contract it must meet.

5.8 Timeline page (hidden until the timeline fragments land)

GET /echo/timeline?id=<agent_id>[&at=<epoch seconds>] is the page that will host the 5.7 renderers, with static/yuzu-echo-timeline.js beside it. Both routes are registered only when kEchoTimelineUi (echo_timeline_page_ui.hpp, copied into page::Deps::echo_timeline_ui) is true. It ships false: the paths do not exist, nothing links to them, and nothing is operator-visible. A signed-out request is redirected to sign in; a missing id is a 400.

• What the shell holds. The page (echo_timeline_page_ui.cpp, shell active_key “echo”) carries no CSS or script of its own beyond the yuzu.css rules and the one script. Slots: #tl-run (an htmx load of /fragments/echo/timeline/run?id=<id>[&at=<n>], with data-moment-url and data-selected-url naming the other two fragments), #tl-moment, #tl-selected, the UTC clock, Play and Speed, and Copy link to this moment. The id is percent-encoded then HTML-escaped; at is used only when it is 1 to 19 digits.
• What the fragments must carry. The script reads numbers, never guesses them: .tl-body[data-from][data-to] (the window), .tl-ph[data-ts] (the resolved moment, emitted only for a valid window, which is the script’s bind signal), moment-panel Previous/Next anchors a[data-ts], block buttons button[data-ts] (with a data-ref when the block is one item), and the selected panel’s linked-item anchors a[data-ref][data-ts]. Every number is plain digits (at most 15): 0x10, 1e3 or a missing data-ts makes the window invalid. The renderers emit all of these. The run fragment is expected to poll its own result with hx-target="this" (as the process tree does). A load inside #tl-run that is refused, never reaches the server or times out ends the run view with a note (“Could not load the record (HTTP n).” or “Could not reach the server.”): the poll does not retry, so the page needs a reload. The run slot’s own 401 is handled by htmx, not by the script: a signed-out HX-Request gets 401 with HX-Redirect: /home, which htmx follows.
• What the script does. It binds once per run instance (a repeated or unrelated settle changes nothing; a new instance rebinds from its own moment). An invalid window, or one without a playhead, gets no controls and no requests. Drag, click and the arrow, Page, Home and End keys move the moment line (UTC). Every committed time change requests the moment panel and, while an item is selected, the selected panel at the same time; the newest request per panel wins and a superseded one is aborted. The panels show whatever the server returns, including offline, not-readable and capped states; a non-2xx is “Could not load this panel (HTTP n).” and an unreachable server “Could not reach the server.” (failures are announced as alerts, a landed panel is not). Every panel request sends HX-Request: true, so the server answers a signed-out one with 401; a 401 or a redirected answer ends the session once: playback stops, both panel requests are aborted and the browser goes to /login.
• Playback. Play/Pause and a 1x / 10x / 60x speed move the moment line through the window already loaded; they do not show live data. Each step advances the line by speed times elapsed time, clamped to the window; a stalled timer (a throttled or suspended tab) counts at most one second of elapsed time per step, so the line never leaps. It stops at the window end (no loop), on Pause, on any manual move, on a failed panel request, when the tab is hidden and when the run instance is replaced. Repeated time changes (playback and a held key) are limited to one panel refresh a second, the newest time wins, and the timer waits for the previous answer; an answer still missing after ten seconds is abandoned and a fresh request made. A click on a block or on Previous / Next, a scrub release, Play restart and the first move after a quiet second refresh the panels at once. A click on what is already shown (the same time and item) asks for nothing, unless its panel failed, in which case it asks again. Stopping on Pause, the window end or a hidden tab commits the exact stop time once so the panels agree with the line. A click on a linked item in the Selected panel refreshes that panel and stops playback; Play at the window end restarts from the window start. Play is disabled with a note when the window is a day or longer or not valid.

The fragments themselves, their permissions and audit are separate work. What the page assumes of them:

• Requests are run?id[&at], moment?id&at and selected?id&ref&at under /fragments/echo/timeline/: stateless, keyed by id, no token. The run poll ends at its result. at parses fail-closed (digits only, no overflow, at=0 invalid), ref has a bounded length, and responses carry Cache-Control: no-store.
• Per-device authorization is theirs: require_scoped_permission, the same posture as the Echo SQL frame (5.5). One usage-class audit verb through emit_behavioral_audit, emitted once per run open (not per moment or selected request), with an explicit choice of fail-closed or proceed.
• An A5 / ADR-1005 parity exception row (issue and revisit date) lands before the flag flips.
• The renderers’ default hrefs are not page deep links; the script intercepts them.
• Keyboard and ARIA limits: the arrow, Page, Home and End keys move the line while the timeline has focus; the range reads the moment as a UTC time; failures are announced, routine refreshes are not. No accessibility conformance is claimed.

6. Permissions matrix

7. Observability

Per docs/observability-conventions.md:

Do not sum yuzu_echo_source_purge_total across surfaces yet. The dashboard fragment and the REST twin write the same series with different result tokens: the fragment distinguishes scope_violation from denied, while REST folds per-device scope denial, missing wiring, and audit failure all into denied and otherwise only ever writes requested. success and agent_not_connected are comparable; nothing else is, and there is no surface label to split them.

The PR-H viewer ships with no process-tree metrics yet (a dashboard read surface); the render-duration histogram + a dispatch counter + a node-count histogram are a tracked SRE follow-up. The seed-age gauge from the original design is removed (there is no seed).

Audit actions: echo.status.scan (Scan fleet — PR-A.A), echo.source.reenable (Re-enable a row — PR-A.A), echo.source.purge (purge — shipped Phase 15.A; also csrf.denied-style cross-origin refusals are audited under echo.source.purge/reenable with detail=csrf_cross_origin), echo.process_tree.read (PR-H — emitted at dispatch and on a successful reconstruction; the device is target_id, never in detail; see docs/user-manual/audit-log.md). The seed-based echo.process_tree.reseed verb is removed (no seed).

8. Cross-references

• docs/scope-walking-design.md — the result-set primitive consumed throughout this page
• docs/yuzu-guardian-design-v1.1.md — agent tamper-resistance, foundational to the process tree’s data quality claim
• docs/yuzu-guardian-windows-implementation-plan.md — Windows-first hardening PR ladder
• agents/plugins/echo/src/echo_aggregator.cpp — the #539 retention pause that the retention-paused list surfaces
• agents/plugins/echo/src/echo_plugin.cpp — the action surface (echo.status, echo.configure, echo.fleet_snapshot, future echo.process_tree, echo.purge_source)
• server/core/src/dashboard_routes.cpp — the existing Echo SQL fragment to be relocated and extended
• docs/data-architecture.md — error code taxonomy, audit envelope conventions
• docs/yaml-dsl-spec.md — DSL surface (gains fromResultSet: per scope-walking-design §7)

9. Sequencing

10. Open questions

• Should the retention-paused list also surface <source>_enabled=true devices that have zero recent rows (silent collector failure)? Useful for SRE but visually noisy in IR; defer to PR-G.
• The “Purge data” action should ideally be replaced by an “Export then purge” flow that puts the rows into a signed evidence bundle before deletion — a SOC 2 CC7.2 evidence requirement. Defer to a follow-up issue once the retention-paused list ships.
• Multi-device re-enable (select-many in the table, single click “Re-enable selected”) is an obvious affordance once the table has rows; ship in PR-A only if the single-row path is solid.