@hyzyn/dsh-docker 0.11.0 → 0.13.0

package/README.en.md

@@ -10,7 +10,7 @@
 - **An explicit one-click "connect local"**: two **non-permanent** entries — with no targets at all it is the primary button in the "no Docker targets configured yet" empty state, and once you have other targets it is the **last item in the target dropdown**, `+ Connect local` (it is deliberately **not** on the toolbar, where being permanent means occupying space and begging for clicks — pure noise) — one click (or picking that item) adds the machine hosting the plugin as a local target and selects it (an existing local target is reused, never duplicated; SSH and custom targets stay untouched), and the same operation is `docker_connect_local` on the agent side. It does **not** change the meaning of an empty `targets`, never invents an implicit default target, never installs Docker / starts a daemon / switches docker contexts, and needs no capability grant (it only adds one local target pointing at the plugin's own host).
 - **Aggregated fetches across targets**: the Overview page fans out over every `targets[]` entry in parallel, and an unreachable target only spoils its own cell; the agent side exposes the same shape through `docker_ps target:"*"` / `docker_attention target:"*"`, so targets never block one another.
 - **"Needs attention" reads authoritative fields**: unhealthy / repeatedly restarting / OOM-killed / non-zero exit / dead; OOM and the real exit code come from one `docker inspect` — the 137 in a `docker ps` summary cannot separate an OOM kill from a manual kill, so filtering on the summary alone must misreport.
-- **Four long-lived SSE streams on one substrate**: log FOLLOW, `docker stats`, `docker events` and `docker pull` all run through the same `openSseStream` (heartbeat / active-stream registry / teardown on disconnect) and differ only in how they end — logs and pulls finish on their own, stats and events are aborted by the browser. Multi-select merged logs recover true cross-container ordering from the `--timestamps` prefix; "pause" freezes rendering only (the stream keeps receiving and flushes in one batch on resume).
+- **Four long-lived SSE streams on one substrate**: log FOLLOW, `docker stats`, `docker events` and `docker pull` all run through the same `openSseStream` (heartbeat / active-stream registry / teardown on disconnect / a `ready` frame as soon as the pipeline is up) and differ only in how they end — logs and pulls finish on their own, stats and events are aborted by the browser. "Connected" and "receiving data" are two different things: the client only counts `ready`, never the arrival of the response headers (see "SSE event protocol"). Multi-select merged logs recover true cross-container ordering from the `--timestamps` prefix; "pause" freezes rendering only (the stream keeps receiving and flushes in one batch on resume).
 - **Read-only by default, capability switches in three tiers**: start / stop / remove, exec and image mutations are independent switches; while one is off the agent tools are **not registered** and the HTTP routes return 403 (the capability does not exist, rather than failing when called). Container names and IDs pass a whitelist, every command is built as argv with single-quote escaping, and passwords / passphrases are referenced as `env:NAME` (resolved through the official credential layer, falling back to the environment) and never sent back to the browser.
 - **Right-click a log into the agent**: select the failing lines in the log view, then right-click for "send to the current session / fill the input box so I can edit first" — the selection travels with its target, container, time window and 20 lines of context on each side (the menu states plainly that the content enters the model context and may carry credentials). Delivery reports itself twice: a **viewport-level toast** (attached to `body`, above the panel and the terminal modal), and — when the terminal panel is open — an **automatic fold of the terminal** (`minimize()` on the `ttyPanel` v2 contract; sessions keep running and the sidebar "Terminal" entry's badge restores it), so the conversation is simply there. On older tty without that call it degrades to the toast's "the conversation is behind the panel" hint. To edit first, use the draft action — **the session input box is the only editing surface** (multi-line, with the full context in view, and exactly what the agent receives), instead of a second, weaker card editor. Locating the target session is version-tolerant: **≤0.1.5** reads `current` off the `sessions.list` snapshot, while **since 0.1.6** that field moved out of the session domain together with view selection, so it reads `retainedBy.mainView > 0` instead (the same test `dsh-client-ui-session` and this repo's codegraph use) — trusting only the legacy field greys out both menu items as "no session open". The same read drives "carry the containers tab across a session switch".
 - **Data-level reuse of dsh-tty, no code coupling**: no tty code is imported and tty needs no source change, so the two install and upgrade independently; with tty present three optional extension points are consumed — connection-bar actions (`ttyConnbar`), the terminal host (`ttyTerminal`: a new tab under the tab/dock carriers, an in-place drawer under the modal) and the terminal-side dock (`ttyPanel.mountPane`, used only by the fallback path) — and each degrades silently without tty or below the required version.
@@ -211,6 +211,14 @@ Inside the panel:
   (2026-10-08 user feedback: "verbose and stiff"): the state label on the left already says the stream is closed,
   so this only says "will not recover on its own — click Reconnect". The cause, the cap and the `MaxSessions`
   details live in this page, not in the UI.
+  **"Receiving events" is only claimed on the host's `ready` frame** (2026-10-11 user report): SSE's `onopen`
+  only means "the response headers arrived" — the host flushes those headers **before** it starts `docker events`,
+  and connecting can stall for tens of seconds when the target is unreachable or the SSH connection is being
+  re-established (D150's "quota full → rebuild the connection" adds another round). During that window the strip
+  used to be green and say "Receiving live (docker events)" while not a single event had arrived. The green dot now
+  waits for `ready` (= the pipeline really came up); until then the state stays at "Connecting to the event stream…"
+  or "Connection lost, reconnecting…" — both of which are true. The log / stats / pull streams follow the same rule
+  (see "SSE event protocol").
 - **Select for merging (temporary multi-select merged logs)**: the toolbar's `Select for merging` enters selection
   mode — a checkbox appears on the left of every card, clicking a card body becomes **select / deselect** (it no
   longer opens details; the action bar collapses temporarily so that multi-selecting does not mis-click
@@ -608,7 +616,8 @@ and reconnect". The record list can be deleted / reset in the settings card (del
 | `docker_ps` | always registered | `target?` (**pass `*` = all targets**), `all?: boolean` | lists containers (name / state / health / image / ports / compose project and service / short ID); by default only running ones, `all:true` includes stopped. With `target:'*'` it returns results grouped by target, and **one unreachable target does not affect the others** (that group carries `error`). Ports are merged across the IPv4/IPv6 dual-stack expansion (one `-p` no longer shows twice, D130); an empty `ports` does **not** mean "nothing exposed" — host-network containers publish on the host itself, and that case now carries a `net` field (D131). The first step of troubleshooting |
 | `docker_attention` | always registered | `target?` (supports `*`), `limit?: number` | a **needs-attention summary**: unhealthy / repeatedly restarting / OOM-killed / non-zero exit / zombie; every item carries `reasons`, `exitCode`, `oomKilled`, `restartCount`. OOM and the real exit code come from one `docker inspect` (a ps summary cannot distinguish a manual kill from 137). The troubleshooting entry point: call it first when you are unsure which machine or container to look at |
 | `docker_inspect` | always registered | `target?`, `id` (required) | `docker inspect`'s authoritative details: state / health check / exit code / restart count / ports / mounts / networks / startup command |
-| `docker_logs` | always registered | `target?`, `id`, `tail?` (1–5000, default `logTailDefault`), `timestamps?`, `since?` | the tail from `docker logs --tail`; `since` uses docker syntax (such as `10m`, `2026-09-09T10:00:00`); over the cap it is marked `truncated` |
+| `docker_logs` | always registered | `target?`, `id`, `tail?` (1–5000, default `logTailDefault`), `timestamps?`, `since?`, `until?` | the tail from `docker logs --tail`; `since` / `until` use docker syntax (e.g. `10m`, `2026-09-09T10:00:00`) to bound a time window; over the cap it is marked `truncated` |
+| `docker_logs_grep` | always registered | `target?`, `id`, `pattern` (required, ≤512 chars), `regexp?`, `ignoreCase?`, `since?`, `until?`, `context?` (0–20, default 2), `limit?` (1–500, default 200), `tail?` (omitted = scan all history), `timestamps?` (on by default) | **server-side log search**: line-by-line filtering in the host (never touches the remote shell, never pipes `| grep`), returns hit lines plus ±context lines, and honestly reports `matched` (all hits even when not returned) / `scanned` / `limited` / `truncated` — "only scanned this far" is distinguishable from "scanned everything"; the scan window is **aligned to line boundaries** (the partial line left by a byte-level cut is never returned as a line, so every entry in `lines` is a complete line). Division of labour with `docker_logs`: error in the recent tail → `docker_logs` (cheaper); buried deep / a specific time window / keywords, error codes, request IDs → this tool. Literal substring by default (grep -F semantics, zero ReDoS); JS regex only with `regexp: true` |
 | `docker_stats` | always registered | `target?`, `ids?` (comma-separated container names/IDs) | a `docker stats --no-stream` snapshot: CPU% / memory usage and share / network IO / block IO / PIDs; omitting `ids` means all running containers. Live following is a panel capability (SSE), and the tool keeps single-value snapshot semantics |
 | `docker_images` | always registered | `target?` | image list (repository:tag / size / created / short ID) |
 | `docker_events` | always registered | `target?`, `since?` (docker `--since` syntax, default `10m`) | a container-event snapshot (`docker events --since <d> --until <now>`, likewise through the server-side allowlist): the nine kinds start / die / stop / kill / oom / health_status / destroy / rename / update, with noise such as `exec_*` already dropped server-side. For continuous observation have the user watch the "Activity" strip in the panel's container list |
@@ -637,7 +646,9 @@ and reconnect". The record list can be deleted / reset in the settings card (del
   static switches above: the switches govern registration (host-level, persistent grant), the tier gate governs
   each registered call (per call, follows the tier immediately). Mechanism:
   [docs/permission-tier-plan.md](../../docs/permission-tier-plan.md).
-- Recommended troubleshooting order: `docker_targets` → `docker_ps` → `docker_logs` →
+- Recommended troubleshooting order: `docker_targets` → `docker_ps` → `docker_logs`
+  (when the tail does not explain the failure, `docker_logs_grep` with `pattern` /
+  `since` / `until` to search deeper) →
   `docker_inspect` → `docker_stats`; for image problems `docker_images` →
   `docker_image_inspect`.
 - With `announceToAgent` on, the plugin injects a capability announcement into the systemPrompt (including the
@@ -673,7 +684,7 @@ returned 403 on Desktop — the symptom was the logs / stats / events / pull str
 
 | Route | Method | Request body | Response |
 | --- | --- | --- | --- |
-| `/config` | GET | — | `{ok:true, config}`: the config snapshot (targets expose only `passwordSet` / `passphraseSet`, plus the read-only `ttyBooks` / `ttyAvailable` / `toolsRegistered`) |
+| `/config` | GET | — | `{ok:true, config}`: the config snapshot (targets expose only `passwordSet` / `passphraseSet`, plus the read-only `ttyBooks` / `ttyAvailable` / `toolsRegistered` / `streamProtocol` — the last one is the SSE frame protocol version the client uses to decide what counts as "ready"; see "SSE event protocol") |
 | `/config` | POST | any subset of the config keys above | `{ok:true, config}`; an unknown key is 400 and invalid JSON is 400 |
 | `/targets` | GET / POST | — | `{ok:true, targets:[{name, kind, label?\|error?}]}` |
 | `/connect-local` | POST | `{}` (the body is ignored) | **Connect local**: reuses or creates a `kind=local` target and returns `{ok:true, result:{name, kind, created, saved, reachable, serverVersion?, message}, config}`; 503 when the host has no settings service and 500 when the save fails (both carry a reason and change no in-memory config). Requires the same-origin proof (it is a write path) but **not** `allowMutations` / `allowExec` |
@@ -710,14 +721,16 @@ returns 500 or 400 plus an `{error}` text.
 
 The four long streams share one piece of infrastructure (`openSseStream`): uniform header writing +
 `flushHeaders()`, a 15s `: ping` heartbeat frame, active-stream registration (a uniform `end` + abort when the plugin
-is disabled / the config is hot-updated / it is uninstalled), and a silent abort when the client disconnects. They
-differ only in the executor and the end reason:
+is disabled / the config is hot-updated / it is uninstalled), a silent abort when the client disconnects, and a
+**`ready` frame sent as soon as the pipeline is actually up** (see the table below and
+`StreamHandlers.onStart`). They differ only in the executor and the end reason:
 
 Each frame is one `event:` line + one JSON `data:` line (single-line JSON encapsulation: newlines / quotes are
 escaped and multi-byte characters are never split by an SSE line boundary), followed by an empty line:
 
 | Event | data | Description |
 | --- | --- | --- |
+| `ready` | `{}` | sent once **the executor is really running** (local child `spawn` / remote channel opened = `StreamHandlers.onStart`): only then does the client consider the stream "receiving data". **Arrival of the response headers (`onopen`) does not count** — those are written by `flushHeaders()` immediately, while connecting (SSH `acquire` / opening the remote channel) can take tens of seconds, and an unreachable target produces nothing but an `error`. If it never starts there is **no** `ready` at all |
 | `line` | `{"d":"..."}` / `{"e":"..."}` | stdout / stderr chunks (not guaranteed to split on line boundaries, so the client reassembles lines). Used by the log stream and the pull stream |
 | `stats` | `ContainerStats` | stats stream only: one frame per container per second, with fields exactly matching the `/stats` snapshot. The server extracts **flat `{...}` objects** (`docker stats` goes through the TTY renderer even when stdout is a pipe, so frames are mixed with `ESC[H/ESC[K/ESC[J`, and parsing by line would drop whole lines) and collapses repeated renders of the same sample, so the client no longer has to parse docker's PascalCase strings |
 | `event` | `{action, name, image, composeProject?, time?, exitCode?}` | event stream only: one container event per frame (event lines outside the allowlist are dropped server-side; fields whose value is null are omitted) |
@@ -756,6 +769,16 @@ The four streams differ only in "executor + end reason":
   own initiative (abort + `end`).
 - A long SSH stream occupies a connection in the pool (a busy count) and idle reclamation (120s) does not kill it by
   mistake; reclamation resumes once the stream ends.
+- **What counts as "ready" (client side)**: the green dot / "following live" only trusts the host's `ready` frame —
+  arriving response headers do not count. Each stream also has a harder piece of evidence as a fallback (receiving it
+  means the pipeline is producing): the first real event for the events stream, the first line for the log stream,
+  the first sample for the stats stream, the first progress frame for the pull stream.
+  **Development skew** (the host process still runs the old code while the browser reads a new `client.js` from disk)
+  is handled by version negotiation: `streamProtocol < 2` in `/config` (or a host old enough to lack the field)
+  means that host never sends `ready`, so the client falls back to the old criterion (headers arrived = connected)
+  and reopens that stream exactly once so the fallback takes effect — measured on 2026-10-11: an old host plus a new
+  client used to be pinned on "Connecting to the event stream…" forever (cards could read containers while the strip
+  kept spinning).
 
 ## Security model
 
@@ -1017,6 +1040,7 @@ Host half (src/index.ts)
   ├─ generic SSE long connection openSseStream (src/index.ts, one piece of infrastructure for all four streams)
   │   ├─ loopback fence + assertRef / assertImageRef + tail clamping (same as the snapshot routes)
   │   ├─ header write + flushHeaders / 15s ping heartbeat / active-stream registry / silent abort when the frontend disconnects
+  │   │   once the pipeline is up, a ready{} frame first (StreamHandlers.onStart: the only thing the client counts as "receiving data")
   │   ├─ /logs/stream: docker logs -f → line{"d"|"e"} + end{container-exit,code}
   │   ├─ /stats/stream (read-only): docker stats normalised line by line → stats{ContainerStats};
   │   │   it does not end naturally, so a frontend disconnect aborts it and docker stats exiting on its own sends end{stats-exit}
@@ -1028,7 +1052,7 @@ Host half (src/index.ts)
   ├─ image routes: /images/inspect (read-only) · /images/remove · /images/prune (allowMutations)
   ├─ network / volume routes: /networks · /volumes and their inspect (read-only), remove / prune (allowMutations)
   └─ agent tools: docker_targets / docker_ps / docker_inspect /
-     docker_logs (snapshot semantics unchanged) / docker_stats / docker_events / docker_images /
+     docker_logs (snapshot semantics unchanged) / docker_logs_grep (server-side search) / docker_stats / docker_events / docker_images /
      docker_image_inspect / docker_networks / docker_volumes (always registered)
      + docker_action / docker_image_remove / docker_image_prune / docker_image_pull
        (allowMutations) / docker_exec (allowExec)
@@ -1084,7 +1108,8 @@ Verification that needs a real daemon follows the manual checklist below.
 (newlines / multi-byte), the local stream lifecycle (fake spawn: multi-byte across chunks, the SIGTERM→SIGKILL
 ladder, close resolve, spawn error) plus the SSH long stream's busy-count pairing / sweeper skip, and the route
 layer's event sequence / heartbeat / silent abort when the client disconnects / uniform wrap-up when the plugin is
-disabled — plus **the `busy` count must return to zero after a long stream is aborted** (D164: neither a far end that
+disabled — plus **`ready` is sent only after `spawn`** (not a single frame before it even though the headers are
+already flushed, and it precedes the first log line) — plus **the `busy` count must return to zero after a long stream is aborted** (D164: neither a far end that
 never confirms the channel close nor eight such leaks in a row may pin the target, and chunks arriving after teardown
 are not delivered) — plus **chunk coalescing** (D151: ten chunks produce a single `line` frame; when the stream ends before the
 window elapses, `end` still comes after those rows) and **exact skip accounting** (D156: frames dropped while a queued
@@ -1123,11 +1148,13 @@ turns red immediately. It depends on the tty preview fixtures
 (generated by `node packages/tty/scripts/preview.mjs`) and **skips with exit 0** when the fixtures or Chrome are
 missing — it is an npm script, not a required vitest entry.
 
-`test/streams.test.ts` (35 cases) covers the **stats stream / event stream / pull stream / networks and volumes /
+`test/streams.test.ts` (46 cases) covers the **stats stream / event stream / pull stream / networks and volumes /
 generic SSE infrastructure**: `statsStream` without `--no-stream` (the same construction point as the snapshot),
 `pullStream`'s `assertImageRef` allowlist, `/stats/stream` normalising line-by-line JSON (including half lines
 across chunks) into `stats` events with the same shape as the `/stats` snapshot, heartbeats, silent abort when the
-client disconnects, `eventsStream`'s argv (no `--since` / `--until`, carrying the `type=container` filter) and the
+client disconnects, **the `ready` frame only once the pipeline is up** (one case per stats / event / pull route:
+zero frames before `spawn` even though the headers are already flushed; two more pin "`ready` precedes the first
+data frame" and "a failed `spawn` sends no `ready`"), `eventsStream`'s argv (no `--since` / `--until`, carrying the `type=container` filter) and the
 `events()` snapshot's `--since` + `--until` (without until it would never exit),
 `parseContainerEvent`'s allowlist / bad-line dropping / health_status suffix / field extraction / compatibility with
 the old `status` field, `/events/stream`'s event sequence and half lines across chunks,
@@ -1162,8 +1189,8 @@ lines), and the gating of the eight `/networks` and `/volumes` endpoints (403 fo
      should **name podman** and say "put podman in 'docker CLI' and it works", while **not**
      rewriting `dockerBin` for you (go back to the settings card — the value is still `docker`).
 4. **Read-only interception**: with both switches off, `/action`, `/exec`, `/images/remove`,
-   `/images/prune`, `/images/pull/stream` all return 403; on the agent side exactly 12 read-only tools are
-   registered (`docker_targets` / `connect_local` / `ps` / `attention` / `inspect` / `logs` / `stats` / `events` / `images` /
+   `/images/prune`, `/images/pull/stream` all return 403; on the agent side exactly 13 read-only tools are
+   registered (`docker_targets` / `connect_local` / `ps` / `attention` / `inspect` / `logs` / `logs_grep` / `stats` / `events` / `images` /
    `image_inspect` / `networks` / `volumes` — see the tool table for the authoritative list), and
    the panel's start / stop / remove, image removal, pruning and pull buttons are greyed out. After turning on
    "allow mutations" these routes and tools appear immediately (no restart needed).
@@ -1253,6 +1280,15 @@ lines), and the gating of the eight `/networks` and `/volumes` endpoints (403 fo
     server-side allowlist);
     after the network drops / `dsh web` restarts, recovery briefly shows a yellow status dot and automatically does
     one full list refresh.
+    **No false green** (2026-10-11 report): point a target's SSH address at a blackhole address (or open the panel
+    while the target is unreachable) → the status dot must be **yellow** with "Connecting to the event stream…", and
+    only turns green once the host confirms `docker events` came up (the `ready` frame); if it cannot connect it
+    finally settles on the red "Event stream closed" + the **Reconnect** button. The log / stats / pull streams
+    follow the same rule (while connecting they each stay on their own "connecting…" copy instead of claiming
+    "following live / receiving live / pulling").
+    One more requirement — **never get stuck**: when the host half is old code (e.g. the host process has not been
+    restarted, so `/config` has no `streamProtocol`) while the browser already loaded the new `client.js`, the strip
+    must fall back to the old criterion and light up — it must not sit on "Connecting to the event stream…" forever.
 18. **Networks / volumes**: the toolbar segments show "Networks" and "Volumes". The network list should contain
     `bridge` / `host` / `none`
     plus project networks created by compose; click one to enter details → the subnet / gateway in the overview match
@@ -1291,6 +1327,25 @@ lines), and the gating of the eight `/networks` and `/volumes` endpoints (403 fo
     Reverse check: switch to Target2 and then immediately back to Target1 (which still cannot connect) → the banner
     should describe Target1's own
     failure, not treat Target2's successful result as Target1's.
+21. **`docker_logs_grep` server-side search** (the shape used for the 2026-10-09 real-machine run): start a
+   container whose log content you know in advance (any image you already have locally; no network needed):
+   `docker run -d --rm --name dsh-grep-probe <local image> sh -c 'echo "[boot] starting"; for i in 1 2 3 4 5; do echo "tick $i ok"; done; echo "FATAL request-id=REQ-7788"; echo "WARN disk 91%" >&2; sleep 3600'`
+   Then have the agent search it with `docker_logs_grep` and **check the raw return value item by item** (do not
+   accept a paraphrase):
+   - search `FATAL` → 1 hit, "scanned 8 lines", the hit marked `>` with ±2 context lines;
+   - `tick [0-9]+` **without** `regexp` → 0 hits; with `regexp=true` → 5 hits (proves the default is **literal**);
+   - `fatal` without `ignoreCase` → 0; with `ignoreCase=true` → 1;
+   - `tick` + `limit=1` → "5 hits" reported but only one window returned, plus the "hits exceed the limit" note (`limited`);
+   - `since=1h` hits / `until=1h` and `since=1s` both 0 hits **and "scanned 0 lines"** (proves `--since`/`--until` really pass through);
+   - search `WARN` → the hit line's stream is `[err]`;
+   - search a container that does not exist → docker's own error text, **not** an empty result.
+   Forcing `truncated` needs a log **>8MB** (the 8MB scan floor is hard; lowering "output limit (KB)" does not move it):
+   let a container write ~300k lines with the needles at the **very head** and the **very tail** → a full scan gives
+   0 hits + the "scan output exceeded the byte limit" note for the former and a hit + the same note for the latter;
+   adding `tail=5000` makes the note disappear in both (proving it reports a **real** scan-side overflow, not
+   "the log is big so it is always true"). Also, **every returned line must be a complete line** (timestamp prefix):
+   the byte gate cuts mid-line, and `lineAlign` drops that partial line (see the real-machine correction in ROADMAP)
+   — a fragment such as `g line 174798` without a timestamp means this has regressed.
 
 ## Version / license
 

package/README.md

@@ -11,7 +11,7 @@
 - **显式一键连接本机**：两个**非常驻**入口——一个目标都没有时是「还没有配置 Docker 目标」空态里的主按钮，已有别的目标时是**目标下拉的末一项** `＋ 连接本机`（工具条上**不挂**：常驻时它既占位又招人点，纯噪音）——一次点击（或选中该项）就把宿主所在机器加成本机目标并选中（已有本机目标则直接复用，不重复创建；SSH / 自定义目标原样保留），agent 侧同一条操作是 `docker_connect_local`。它**不**改空 `targets` 的语义、**不**凭空造隐式默认目标、**不**自动装 Docker / 起 daemon / 切 docker context，也不需要任何能力授权（只加一条指向插件自身的本机目标）。
 - **多目标聚合取数**：总览页对全部 `targets[]` 并行请求，单个目标不可达只污染自己那一格；agent 侧同一口径由 `docker_ps target:"*"` / `docker_attention target:"*"` 暴露，跨目标不互相阻塞。
 - **「需关注」读权威字段**：不健康 / 反复重启 / OOM 被杀 / 非零退出 / 僵死；OOM 与真实退出码由一次 `docker inspect` 补齐——`docker ps` 摘要里的 137 分不出 OOM 与手动 kill，只按摘要筛必然误报。
-- **四条 SSE 长流共用一套基建**：日志 FOLLOW、`docker stats`、`docker events`、`docker pull` 走同一个 `openSseStream`（心跳 / 活跃流登记 / 断开清理），差异只在收尾语义——日志与拉取自然结束，统计与事件由前端主动断。多选聚合日志按 `--timestamps` 前缀还原跨容器真实时序，「暂停」只冻结渲染（流继续接收，恢复时一次性补齐）。
+- **四条 SSE 长流共用一套基建**：日志 FOLLOW、`docker stats`、`docker events`、`docker pull` 走同一个 `openSseStream`（心跳 / 活跃流登记 / 断开清理 / 管道起来后先发一帧 `ready`），差异只在收尾语义——日志与拉取自然结束，统计与事件由前端主动断。「连上了」与「在收数据」是两件事：客户端只认 `ready`，响应头到达不算（见「SSE 事件协议」）。多选聚合日志按 `--timestamps` 前缀还原跨容器真实时序，「暂停」只冻结渲染（流继续接收，恢复时一次性补齐）。
 - **默认只读，能力开关分三级**：启停删 / exec / 镜像变更各自独立开关，未开启时 agent 工具**不注册**、HTTP 路由 403（能力不存在，而非调用后报错）；开关的**提权走两条带外通道**（启动环境变量 / 卡片里就地确认，见下条）；容器名与 ID 过白名单，命令一律 argv 构造 + 单引号转义，密码 / 口令以 `env:NAME` **凭据引用**（官方凭据层解析，缺失时退回环境变量）且永不回传浏览器。
 - **与 dsh-tty 数据级复用、代码级不耦合**：不 import 任何 tty 代码，tty 也无需改一行源码，两者可各自安装与升级；装了 tty 则消费三个可选扩展点——连接栏动作（`ttyConnbar`）、终端承载（`ttyTerminal`：标签 / dock 承载下经 `open` 新开标签，模态下经 `mount` 就地嵌入抽屉）、以及只在兜底路径用到的终端右侧 dock（`ttyPanel.mountPane`）；未装或版本不足逐项静默降级。
 
@@ -188,6 +188,12 @@ add。装完重启 `dsh web`，侧边栏出现「容器」入口；设置 →
   断开时右侧那句提示是**折叠头里的单行小字**，所以刻意写短（2026-10-08 用户反馈
   「啰嗦又生硬」）：状态行左边已经在说「事件流已断开」，这句只说「不会自动恢复，点
   「重连」」——成因、上限与 `MaxSessions` 那一串写在本页，不塞进界面。
+  **「在收事件」只认宿主那帧 `ready`**（2026-10-11 用户现场）：SSE 的 `onopen` 只等于
+  「响应头到了」——宿主是先把响应头 flush 出去、**再去起** `docker events`，而目标不可达 /
+  SSH 正在重连时建连可以卡十几秒（D150 的「槽位满 → 重建连接」还会再来一轮）。那段时间
+  活动条原本已经亮成绿色的「实时接收中（docker events）」，一个事件都还没收到。现在绿点
+  只认 `ready`（= 管道真的起来了）；此前停在「正在连接事件流…」/「连接中断，正在自动
+  重连…」——两种都是实话。日志 / 统计 / 拉取三条流同一口径（见「SSE 事件协议」）。
 - **聚合选择（临时多选聚合日志）**：工具条的 `聚合选择` 进入选择态——每张卡片
   左侧出现勾选框，点卡片本体变成**勾选 / 取消**（不再进详情；动作条暂时收起，
   免得一边多选一边误点启停删），工具条与列表之间出现操作条：「已选 N 个容器」+
@@ -579,7 +585,8 @@ challenge 的 TTL 与探测周期各自独立，所以文案只说「执行后
 | `docker_ps` | 恒注册 | `target?`（**传 `*` = 全部目标**）、`all?: boolean` | 列容器（名称 / 状态 / 健康 / 镜像 / 端口 / compose 项目与服务 / 短 ID）；默认只列运行中，`all:true` 含已停止。`target:'*'` 时按目标分组返回，**单个目标不可达不影响其他目标**（该组带 `error`）。端口是 IPv4/IPv6 双栈归并后的映射（同一次 `-p` 不再出现两遍，D130）；`ports` 为空**不等于**没暴露端口——host 网络容器的端口即宿主机端口，这种情况会给 `net` 字段（D131）。排障第一步 |
 | `docker_attention` | 恒注册 | `target?`（支持 `*`）、`limit?: number` | **需关注汇总**：不健康 / 反复重启 / 被 OOM 杀 / 非零退出 / 僵死；每条带 `reasons`、`exitCode`、`oomKilled`、`restartCount`。OOM 与真实退出码来自一次 `docker inspect`（ps 摘要里 137 无法区分手动 kill）。排障入口：不确定从哪台/哪个容器看起时先调它 |
 | `docker_inspect` | 恒注册 | `target?`、`id`（必填） | `docker inspect` 的权威详情：状态 / 健康检查 / 退出码 / 重启次数 / 端口 / 挂载 / 网络 / 启动命令 |
-| `docker_logs` | 恒注册 | `target?`、`id`、`tail?`（1~5000，默认 `logTailDefault`）、`timestamps?`、`since?` | `docker logs --tail` 尾部；`since` 用 docker 语法（如 `10m`、`2026-09-09T10:00:00`）；超上限标记 `truncated` |
+| `docker_logs` | 恒注册 | `target?`、`id`、`tail?`（1~5000，默认 `logTailDefault`）、`timestamps?`、`since?`、`until?` | `docker logs --tail` 尾部；`since` / `until` 用 docker 语法（如 `10m`、`2026-09-09T10:00:00`）圈时间窗；超上限标记 `truncated` |
+| `docker_logs_grep` | 恒注册 | `target?`、`id`、`pattern`（必填，≤512 字符）、`regexp?`、`ignoreCase?`、`since?`、`until?`、`context?`（0~20，默认 2）、`limit?`（1~500，默认 200）、`tail?`（缺省 = 扫全部历史）、`timestamps?`（默认开） | **日志服务端检索**：宿主侧逐行过滤（不碰远端 shell、不拼 `\| grep`），返回命中行 + 前后上下文，并如实报告 `matched`（全量命中数，即使没返回）/ `scanned` / `limited` / `truncated`——「只扫到这些」与「扫完了没更多」可区分；扫描窗口**对齐到行边界**（按字节截断处的半行不当作一行返回，所以 `lines` 里每一行都是完整的行）。与 `docker_logs` 的分工：报错就在最近尾部 → `docker_logs`（便宜）；埋在深处 / 特定时间窗 / 找关键词、异常码、请求 ID → 本工具。默认字面子串（grep -F 语义，零 ReDoS），`regexp: true` 才按 JS 正则 |
 | `docker_stats` | 恒注册 | `target?`、`ids?`（逗号分隔的容器名/ID） | `docker stats --no-stream` 快照：CPU% / 内存用量与占比 / 网络 IO / 块 IO / PIDs；`ids` 省略 = 全部运行中容器。实时跟随是面板能力（SSE），工具保持单值快照语义 |
 | `docker_images` | 恒注册 | `target?` | 镜像列表（仓库:标签 / 大小 / 创建时间 / 短 ID） |
 | `docker_events` | 恒注册 | `target?`、`since?`（docker `--since` 语法，默认 `10m`） | 容器事件快照（`docker events --since <d> --until <now>`，同样过服务端白名单）：start / die / stop / kill / oom / health_status / destroy / rename / update 九类，`exec_*` 等噪音已在服务端丢掉。要持续观察请让用户看面板容器列表的「活动」条 |
@@ -605,7 +612,8 @@ challenge 的 TTL 与探测周期各自独立，所以文案只说「执行后
   `tier-gate: services absent (…), per-call gate disabled`。它与上面两个静态开关是**双层**：
   静态开关管注册（宿主级、持久授权），档位闸管已注册调用的放行（逐调用、随档位即时变）。
   机制见 [docs/permission-tier-plan.md](../../docs/permission-tier-plan.md)。
-- 推荐排障顺序：`docker_targets` → `docker_ps` → `docker_logs` →
+- 推荐排障顺序：`docker_targets` → `docker_ps` → `docker_logs`（尾部看不到成因就
+  `docker_logs_grep` 带 `pattern` / `since` / `until` 检索深处）→
   `docker_inspect` → `docker_stats`；镜像排查 `docker_images` →
   `docker_image_inspect`。
 - `announceToAgent` 开启时，插件向 systemPrompt 注入一段能力公告（含「默认
@@ -637,7 +645,7 @@ challenge 的 TTL 与探测周期各自独立，所以文案只说「执行后
 
 | 路由 | 方法 | 请求体 | 返回 |
 | --- | --- | --- | --- |
-| `/config` | GET | — | `{ok:true, config}`：配置快照（targets 只给 `passwordSet` / `passphraseSet`，另附只读的 `ttyBooks` / `ttyAvailable` / `toolsRegistered`） |
+| `/config` | GET | — | `{ok:true, config}`：配置快照（targets 只给 `passwordSet` / `passphraseSet`，另附只读的 `ttyBooks` / `ttyAvailable` / `toolsRegistered` / `streamProtocol`——最后这个是 SSE 帧协议版本，客户端据此决定「怎样才算已就绪」，见「SSE 事件协议」） |
 | `/config` | POST | 上表配置键的任意子集 | `{ok:true, config}`；未知键 400，非法 JSON 400 |
 | `/targets` | GET / POST | — | `{ok:true, targets:[{name, kind, label?\|error?}]}` |
 | `/connect-local` | POST | `{}`（请求体被忽略） | **一键连接本机**：复用或新建 `kind=local` 目标并返回 `{ok:true, result:{name, kind, created, saved, reachable, serverVersion?, message}, config}`；宿主没有 settings 服务时 503，保存失败时 500（都带原因且不改内存配置）。要求同源证明（它是写路径），但**不需要** `allowMutations` / `allowExec` |
@@ -674,13 +682,15 @@ challenge 的 TTL 与探测周期各自独立，所以文案只说「执行后
 
 四条长流共用同一份基建（`openSseStream`）：统一写头 + `flushHeaders()`、15s
 一帧 `: ping` 心跳、活跃流登记（插件禁用 / 配置热更新 / 卸载时统一 `end` +
-abort）、客户端断开静默中止。各自只差执行器与结束原因：
+abort）、客户端断开静默中止，以及**管道起来后先发一帧 `ready`**（下表 + 客户端的
+「绿点只认 ready」口径）。各自只差执行器与结束原因：
 
 每帧一行 `event:` + 一行 JSON `data:`（JSON 单行封装：换行 / 引号被转义，
 多字节字符不会被 SSE 行边界截断），随后空行：
 
 | 事件 | data | 说明 |
 | --- | --- | --- |
+| `ready` | `{}` | **执行器真的起来了**才发一帧（本机子进程 `spawn` / 远端通道已开 = `StreamHandlers.onStart`）：客户端据此才认为「在收数据」。**响应头到达（`onopen`）不算**——响应头由 `flushHeaders()` 立刻写出去，而建连（SSH `acquire` / 远端开通道）可能卡十几秒，目标不可达时干脆只有 `error`。起不来就**没有** `ready` |
 | `line` | `{"d":"..."}` / `{"e":"..."}` | stdout / stderr 分片（不保证按行切，客户端自行拼行）。日志流与拉取流用 |
 | `stats` | `ContainerStats` | 统计流专用：每秒每个容器一帧，字段与 `/stats` 快照完全一致。服务端按**扁平 `{...}` 抽取**（`docker stats` 即便 stdout 是管道也走 TTY 渲染器，帧里混着 `ESC[H/ESC[K/ESC[J`，按行解析会整行丢掉）并折叠同一采样的重复渲染，客户端不必再解析 docker 的 PascalCase 字符串 |
 | `event` | `{action, name, image, composeProject?, time?, exitCode?}` | 事件流专用：一帧一个容器事件（白名单外的事件行在服务端就丢了；值为 null 的字段省略） |
@@ -715,6 +725,13 @@ abort）、客户端断开静默中止。各自只差执行器与结束原因：
   热更新 / 卸载 → 服务端主动收尾（abort + `end`）。
 - SSH 的长流会占用连接池里的连接（busy 计数），空闲回收（120s）不会误杀；
   流结束后恢复回收。
+- **「已就绪」的判据（客户端侧）**：绿点 /「实时跟随中」只认宿主那帧 `ready`——响应头到了
+  不算。此外每条流还有一条「更硬的证据」兜底（收到它就等于管道在产数据）：事件流的第一条
+  真实事件、日志流的第一行、统计流的第一个采样、拉取流的第一帧进度。
+  **开发档错位**（宿主进程还跑着旧代码、浏览器却从磁盘读到新的 `client.js`）另有版本协商：
+  `/config` 的 `streamProtocol < 2`（或老到没有这个字段）说明该宿主从不发 `ready`，客户端
+  退回旧判据（响应头到了就算连上），并只重开一次那条流让回退判据生效——2026-10-11 实测：
+  旧宿主 + 新客户端原本会被钉死在「正在连接事件流…」（卡片能读到容器，活动条却在转）。
 
 ## 安全模型
 
@@ -966,6 +983,7 @@ abort）、客户端断开静默中止。各自只差执行器与结束原因：
   ├─ 通用 SSE 长连接 openSseStream（src/index.ts，四条流共用一份基建）
   │   ├─ loopback 围栏 + assertRef / assertImageRef + tail 夹紧（与快照路由一致）
   │   ├─ 写头 + flushHeaders / 15s ping 心跳 / 活跃流登记 / 前端断开静默 abort
+  │   │   管道起来后先发 ready{}（StreamHandlers.onStart：客户端只认它当「在收数据」）
   │   ├─ /logs/stream：docker logs -f → line{"d"|"e"} + end{container-exit,code}
   │   ├─ /stats/stream（只读）：docker stats 逐行归一 → stats{ContainerStats}；
   │   │   不会自然结束，前端断连即 abort，docker stats 自退则 end{stats-exit}
@@ -977,7 +995,7 @@ abort）、客户端断开静默中止。各自只差执行器与结束原因：
   ├─ 镜像路由：/images/inspect（只读）· /images/remove · /images/prune（allowMutations）
   ├─ 网络 / 卷路由：/networks · /volumes 与各自的 inspect（只读）、remove / prune（allowMutations）
   └─ agent 工具：docker_targets / docker_ps / docker_inspect /
-     docker_logs（快照语义不变）/ docker_stats / docker_events / docker_images /
+     docker_logs（快照语义不变）/ docker_logs_grep（服务端检索）/ docker_stats / docker_events / docker_images /
      docker_image_inspect / docker_networks / docker_volumes（恒注册）
      + docker_action / docker_image_remove / docker_image_prune / docker_image_pull
        （allowMutations）/ docker_exec（allowExec）
@@ -1036,14 +1054,17 @@ loopback 403（含三条流路由）、容器名 / 镜像引用注入尝试被
 多字节）、本地流生命周期（假 spawn：跨 chunk 多字节、SIGTERM→SIGKILL 阶梯、
 close resolve、spawn error）与 SSH 长流的 busy 计数配对 / sweeper 跳过、以及
 路由层的事件序列 / 心跳 / 客户端断开静默中止 / 插件禁用统一收尾，以及
+**`ready` 只在 `spawn` 之后发**（响应头已 flush 也一帧不发，且排在第一条日志行前面）、
 **`tail=0` 只跟随不补历史**（D133）、**背压不重写已写过的帧**与**积压时丢最旧 + `skip` 通知、
 不掐流**（D153）、**skip 账目精确**（D156：skip 排队期间再丢弃，两段缺口都要报——
 46 块逐块对账「每一帧要么送达、要么被 skip 记账」）、
 **中止长流后 `busy` 必须归零**（D164：远端不确认关通道、累积 8 次都不会把目标钉死，
 且收尾后的分片不再投递）、
 以及**分片合帧**（D151：十个分片只出一个 `line` 帧；未到窗口就收尾时 `end` 仍排在
-这些行之后）。合帧器本身的规则（窗口合并 / 攒满即推 / flush 幂等 / dispose 停表）在
-`test/sse-coalesce.test.ts`（6 例）。
+这些行之后）、**`ready` 帧只在管道起来后发**（统计 / 事件 / 拉取三条路由各一例：
+`spawn` 之前一帧都没有——响应头已经 flush 了也不算；另两例钉住「`ready` 排在第一条
+数据帧前面」与「起不来（`spawn` 失败）不发 `ready`」）。合帧器本身的规则（窗口合并 /
+攒满即推 / flush 幂等 / dispose 停表）在 `test/sse-coalesce.test.ts`（6 例）。
 
 `test/log-window.test.ts`（17 例）覆盖**窗口化挂载的纯逻辑**（D152，`client-src/log-window.js`）：
 实测高度进缓存而没量过的行用估算、`layout` 非贴底时的窗口定位与上下垫高自洽、贴底时锚到
@@ -1074,7 +1095,7 @@ close resolve、spawn error）与 SSH 长流的 busy 计数配对 / sweeper 跳
 （`node packages/tty/scripts/preview.mjs` 生成），夹具或 Chrome 缺失时**跳过并 exit 0**
 —— 它是 npm script，不是 vitest 必跑项。
 
-`test/streams.test.ts`（35 例）覆盖**统计流 / 事件流 / 拉取流 / 网络卷 / 通用 SSE 基建**：
+`test/streams.test.ts`（46 例）覆盖**统计流 / 事件流 / 拉取流 / 网络卷 / 通用 SSE 基建**：
 `statsStream` 不带 `--no-stream`（与快照同一构造点）、`pullStream` 的
 `assertImageRef` 白名单、`/stats/stream` 把逐行 JSON（含跨 chunk 的半行）归一成
 `stats` 事件且形状与 `/stats` 快照一致、心跳、客户端断开静默中止、
@@ -1110,9 +1131,9 @@ network / volume 的 ls·inspect 解析容错（字符串布尔、缺 `Mountpoin
      **点名 podman** 并说明「把『docker CLI』填成 podman 就能用」，同时**不该**替你
      改 `dockerBin`（回头去设置卡片看，值仍是 `docker`）。
 4. **只读拦截**：两个开关都关时，`/action`、`/exec`、`/images/remove`、
-   `/images/prune`、`/images/pull/stream` 全部 403；agent 侧恒注册 12 个只读工具
-   （`docker_targets` / `connect_local` / `ps` / `attention` / `inspect` / `logs` / `stats` / `events` /
-   `images` / `image_inspect` / `networks` / `volumes`，数量以工具表为准），
+   `/images/prune`、`/images/pull/stream` 全部 403；agent 侧恒注册 13 个只读工具
+   （`docker_targets` / `connect_local` / `ps` / `attention` / `inspect` / `logs` /
+   `logs_grep` / `stats` / `events` / `images` / `image_inspect` / `networks` / `volumes`，数量以工具表为准），
    面板的启停删 / 镜像删除 / 清理 / 拉取按钮置灰。打开「允许变更操作」后这些
    路由与工具立即出现（无需重启）。
 5. **日志 / 统计 / 镜像**：`tail` 与 `timestamps` / `since` 生效；统计显示
@@ -1182,6 +1203,14 @@ network / volume 的 ls·inspect 解析容错（字符串布尔、缺 `Mountpoin
    形式）；点标题可折叠（事件流不中断，展开后仍是累积的最新 8 条）；
    `docker exec` 连续几次**不产生任何事件**（`exec_*` 已被服务端白名单丢掉）；
    断网 / 重启 `dsh web` 后恢复时状态点短暂黄色并自动补一次全量列表刷新。
+   **不得出现假绿**（2026-10-11 现场）：把某个目标的 SSH 地址改成黑洞地址（或在目标
+   不可达时打开面板）→ 状态点必须是**黄色**的「正在连接事件流…」，只有宿主确认
+   `docker events` 起来（`ready` 帧）才转绿；连不上时最终落到红色的「事件流已断开」+
+   「重连」按钮。日志 / 统计 / 拉取三条流同理（建连期间各自停在「正在连接…」，不会
+   先说「实时跟随中 / 实时接收中 / 正在拉取」）。
+   另有一条**不许卡死**：宿主半体仍是旧代码（例如宿主进程还没重启、`/config` 里没有
+   `streamProtocol`）而浏览器已加载新 `client.js` 时，活动条必须退回旧判据并点亮——
+   不能永远停在「正在连接事件流…」。
 18. **网络 / 卷**：工具条分段出现「网络」「卷」。网络列表应含 `bridge` / `host` / `none`
    与 compose 创建的项目网络；点某条进详情 → 概览里子网 / 网关与 `docker network
    inspect` 一致、`internal` 网络带徽标，「接入的容器」页签列出容器名与 IPv4。
@@ -1205,6 +1234,23 @@ network / volume 的 ls·inspect 解析容错（字符串布尔、缺 `Mountpoin
    目标1 的容器。从总览点 目标1 那张红色计数卡进去，同样不该看到上一个目标的失败。
    反向验证：切到目标2 后立刻切回目标1（它仍然连不上）→ 横幅应写的是目标1 自己的
    失败，而不是把目标2 的成功结果当成了目标1 的。
+21. **`docker_logs_grep` 服务端检索**（2026-10-09 真机实测的口径）：起一个日志内容已知的容器
+   （用本地已有镜像即可，不必联网）：
+   `docker run -d --rm --name dsh-grep-probe <本地镜像> sh -c 'echo "[boot] starting"; for i in 1 2 3 4 5; do echo "tick $i ok"; done; echo "FATAL request-id=REQ-7788"; echo "WARN disk 91%" >&2; sleep 3600'`
+   然后在会话里让 agent 用 `docker_logs_grep` 检索它，**逐项看原始返回值**（别接受转述）：
+   - 找 `FATAL` → 命中 1 行、「扫描 8 行」、命中行标 `>` 且带 ±2 行上下文；
+   - `tick [0-9]+` **不传** `regexp` → 0 命中；传 `regexp=true` → 5 命中（证明默认是**字面**匹配）；
+   - `fatal` 不传 `ignoreCase` → 0；传 `ignoreCase=true` → 1；
+   - `tick` + `limit=1` → 「命中 5 行」但只返回 1 组窗口，并出现「命中超过上限」提示（`limited`）；
+   - `since=1h` 命中 / `until=1h` 与 `since=1s` 各 0 命中**且「扫描 0 行」**（证明 `--since`/`--until` 真透传）；
+   - 找 `WARN` → 命中行的 stream 是 `[err]`；
+   - 检索不存在的容器 → 报 docker 原文错误，**不是**空结果。
+   `truncated` 只能用 **>8MB** 日志逼出来（扫描侧 8MB 硬下限，调小「输出上限（KB）」没用）：
+   让容器打 ~30 万行、探针分别写在**最开头**与**最末尾** → 全量扫时前者 0 命中 + 「扫描输出超过
+   字节上限」提示，后者命中 + 同一提示；加 `tail=5000` 后两者都不再出现该提示（证明它报的是
+   扫描侧**真溢出**，不是「日志大就恒 true」）。另外**返回的每一行都必须是完整行**（带时间戳
+   前缀）：字节闸的切口会切在行中间，`lineAlign` 负责丢掉那个半行（见 ROADMAP 的真机验收补正）
+   —— 看到 `g line 174798` 这种没时间戳的碎片，就是这条回归了。
 
 ## 版本 / 许可证
 

package/client-src/index.js

@@ -1998,6 +1998,27 @@ function canReconnectEvents(status) {
   return status === 'closed'
 }
 
+/**
+ * 这条宿主**会不会发 `ready` 帧**（`/config` 的 `streamProtocol`，见 src/index.ts）。
+ *
+ * 为什么需要版本协商：客户端半体与宿主半体同包同版本，正常永远一致；但开发档里会出现
+ * 「宿主进程还跑着旧代码（模块已在内存里）、浏览器却从磁盘读到新的 client.js」——旧宿主
+ * 从不发 `ready`，新客户端若死等就会把用户钉在「正在连接事件流…」上（2026-10-11 用户在
+ * test profile 上实测到：卡片能读到容器，活动条却永远在转）。
+ *
+ * 判据：
+ *   - `streamProtocol >= 2` → 发 ready（本版宿主）；
+ *   - 字段存在但更小（0 / 1）→ 老宿主：退回旧判据（响应头到了就算连上）；
+ *   - `config` 还没加载（null）→ 按**发 ready** 处理（真宿主一定会答 `/config`），
+ *     加载完成时由 Panel 里那段 effect 纠正（hostReadyFrameRef）。
+ *   - 字段整个缺失（比本包更老的宿主）→ 按「不发 ready」处理：它不可能有这帧。
+ */
+function hostSendsReadyFrame(config) {
+  if (config === null || typeof config !== 'object') return true
+  const value = Number(config.streamProtocol)
+  return Number.isFinite(value) ? value >= 2 : false
+}
+
 /**
  * 从事件流的 `error` 事件里解出**服务端给的原因**（D164）。
  *
@@ -3773,6 +3794,8 @@ window.__ModuleLoader__.load({
           let payload = null
           try { payload = JSON.parse(event.data) } catch { return }
           if (payload === null || typeof payload !== 'object') return
+          // 真的来了一个采样 = 管道在产数据：旧宿主（不发 ready）下这就是「已就绪」的证据
+          setStatsStatus('open')
           const cpu = typeof payload.cpuPercent === 'number' ? payload.cpuPercent : null
           const mem = typeof payload.memPercent === 'number' ? payload.memPercent : null
           setStats(payload)
@@ -3812,10 +3835,14 @@ window.__ModuleLoader__.load({
         es.addEventListener('stats', onStats)
         es.addEventListener('end', onEnd)
         es.addEventListener('error', onError)
-        es.onopen = () => {
+        /*
+         * 统计流的「已在跟随」同样只认 `ready`（宿主把 `docker stats` 真起来了）；
+         * `onopen` 只证明响应头到了，目标连不上时它会先亮成「实时跟随中（docker stats）」。
+         */
+        es.addEventListener('ready', () => {
           setStatsStatus('open')
           setStatsNotice('')
-        }
+        })
         return close
       }, [active, tab, statsFollow, props.target, item.id])
 
@@ -4665,6 +4692,8 @@ window.__ModuleLoader__.load({
           if (payload === null || typeof payload !== 'object') return
           const text = typeof payload.d === 'string' ? payload.d : (typeof payload.e === 'string' ? payload.e : '')
           if (text === '') return
+          // 真的来了逐层进度 = `docker pull` 在跑：旧宿主（不发 ready）下这就是就绪证据
+          setStatus('open')
           const merged = mergeProgress(linesRef.current, text, pendingRef.current)
           linesRef.current = merged.lines
           pendingRef.current = merged.pending
@@ -4699,7 +4728,8 @@ window.__ModuleLoader__.load({
         es.addEventListener('line', onLine)
         es.addEventListener('end', onEnd)
         es.addEventListener('error', onError)
-        es.onopen = () => setStatus('open')
+        // 拉取流同理：`ready` = 宿主的 `docker pull` 真起来了（onopen 只证明响应头到了）
+        es.addEventListener('ready', () => { setStatus('open') })
         return () => {
           close()
           pendingRef.current = ''
@@ -5902,6 +5932,18 @@ window.__ModuleLoader__.load({
       const eventsOpenedRef = useRef({ opened: false })
       /** 上一次建流时看到的**手动**重连令牌（D160）：用来认出「这次 effect 跑是用户点的重连」。 */
       const eventsReconnectRef = useRef(0)
+      /**
+       * 宿主会不会发 `ready` 帧（`/config` 的 `streamProtocol`，见 hostSendsReadyFrame）。
+       *
+       * 默认 true（config 还没加载时按新宿主）：旧宿主靠各自的兜底判据点亮，不会把用户钉在
+       * 「正在连接…」上。config 到达后由下面那段 effect 纠正。
+       */
+      const hostReadyFrameRef = useRef(true)
+      /**
+       * 事件流的响应头已经收到、但还没拿到「已就绪」（`ready`）——只用于「config 晚到、
+       * 而宿主是旧的」这种开发档错位：那种组合下要补一次重开，让 onopen 的回退判据生效。
+       */
+      const eventsLinkedRef = useRef(false)
       /** 打开中的容器详情：{ id, tab, item }（item 为快照，列表刷新后优先用新数据）。 */
       const [detail, setDetail] = usePanelState('detail', null)
       const [refreshToken, setRefreshToken] = useState(0)
@@ -6555,6 +6597,11 @@ window.__ModuleLoader__.load({
           let payload = null
           try { payload = JSON.parse(raw.data) } catch { return }
           if (payload === null || typeof payload !== 'object') return
+          /*
+           * 真的收到一条事件 = 管道在产数据，这是比 `ready` 更硬的证据（旧宿主 / 仿真宿主
+           * 没有 ready 帧时靠它点亮）。放在 lastEvent 更新之前无所谓：它只看状态。
+           */
+          if (eventsLinkedRef.current) applyEventsReady()
           setEvents((list) => pushEvent(list, payload, EVENT_BUFFER_LIMIT))
           debounced.schedule()
         }
@@ -6586,7 +6633,15 @@ window.__ModuleLoader__.load({
         es.addEventListener('event', onEvent)
         es.addEventListener('end', onEnd)
         es.addEventListener('error', onError)
-        es.onopen = () => {
+        /*
+         * 「连上了」与「真的在收事件」是两件事（2026-10-11 用户现场）：宿主是先把 SSE
+         * 响应头 flush 出去、**再**去起 `docker events`（见 src/index.ts 的
+         * `readyOnStart`），所以 `onopen` 只证明响应头到了——目标连不上 / SSH 正在重连时
+         * `acquire()` 可能卡十几秒，活动条却已经亮成绿色的「实时接收中（docker events）」。
+         * 现在绿点只认宿主那句「管道真的起来了」（`ready` 帧 ← StreamHandlers.onStart）。
+         */
+        const applyEventsReady = () => {
+          eventsLinkedRef.current = false
           setEventsStatus('open')
           // 连上了就说明上次那条拒绝原因已经过去（D164）：留着会让人以为现在还坏着
           setEventsRefused('')
@@ -6603,12 +6658,39 @@ window.__ModuleLoader__.load({
           hadOpen = true
           eventsOpenedRef.current.opened = true
         }
+        es.addEventListener('ready', applyEventsReady)
+        /*
+         * `onopen` 只说明「响应头到了」——除非**宿主是旧的**（/config 的 streamProtocol < 2，
+         * 或老到没有这个字段）：那种宿主从不发 `ready`，死等会永远停在「正在连接事件流…」。
+         * 那种组合下退回旧判据（响应头到了就算连上），并把 `eventsLinkedRef` 记上，
+         * 供 config 晚到时那段 effect 补一次重开（2026-10-11 用户在 test profile 上实测到）。
+         */
+        es.onopen = () => {
+          eventsLinkedRef.current = true
+          if (!hostReadyFrameRef.current) applyEventsReady()
+        }
         return () => {
+          eventsLinkedRef.current = false
           close()
           debounced.cancel()
         }
       }, [active, view, target, eventsReconnect])
 
+      /*
+       * 宿主版本协商（2026-10-11）：`streamProtocol < 2` 的宿主从不发 `ready`。
+       *
+       * config 正常在挂载时就到了（早于「选目标 → 建流」），那种情况下 events effect 里的
+       * `onopen` 直接走回退判据；这里只兜「config 晚于建流」的一拍：那时流已经收到响应头、
+       * 界面还停在「正在连接事件流…」，重开一次让 onopen 生效。只在版本**变化**时动手，
+       * 下一次 onopen 就会置 open，不会循环。
+       */
+      useEffect(() => {
+        const next = hostSendsReadyFrame(config)
+        if (hostReadyFrameRef.current === next) return
+        hostReadyFrameRef.current = next
+        if (!next && eventsLinkedRef.current) setEventsReconnect((value) => value + 1)
+      }, [config])
+
       useEffect(() => {
         if (notice === '') return undefined
         const timer = setTimeout(() => setNotice(''), 4000)
@@ -8805,6 +8887,7 @@ window.__ModuleLoader__.load({
       debounce: makeDebounced,
       canReconnect: canReconnectEvents,
       errorMessage: eventsErrorMessage,
+      hostSendsReadyFrame,
     }
     /*
      * 同一类测试缝：总览的折叠逻辑与**正文渲染**都是纯函数（正文刻意写成普通函数而不是

package/client-src/log-stream.js

@@ -92,6 +92,21 @@ export function subscribeLogStream(options) {
     options.onStatus?.('connecting')
     const next = new EventSource(buildUrl(tailNow))
     source = next
+    /*
+     * 「已就绪」只认两条证据（每次建流各自一份，见下）：
+     *   1. 宿主的 `ready` 帧 —— 管道（远端通道 / 子进程）真的起来了；
+     *   2. **第一行真实日志** —— 有数据就是更硬的证据，顺带兜住「宿主还是旧版本、
+     *      从不发 ready」的开发档错位（否则界面会永远停在「正在连接日志流…」）。
+     * `onopen` 一条都不算：它只证明 SSE 响应头到了。
+     */
+    let opened = false
+    const markOpen = () => {
+      if (opened) return
+      opened = true
+      attempt = 0
+      options.onStatus?.('open')
+      options.onOpen?.()
+    }
     next.addEventListener('line', (event) => {
       if (source !== next) return
       let payload = null
@@ -101,6 +116,7 @@ export function subscribeLogStream(options) {
         return
       }
       if (payload === null || typeof payload !== 'object') return
+      markOpen()
       if (typeof payload.d === 'string') options.onLine?.(payload.d)
       else if (typeof payload.e === 'string') options.onLine?.(payload.e)
     })
@@ -151,11 +167,18 @@ export function subscribeLogStream(options) {
       // 连接层错误：不再交给浏览器自动重连（它会重放 tail），改走手动重连
       reconnect()
     })
-    next.onopen = () => {
+    /*
+     * 宿主的 `ready` 帧（见 open 里的两条证据）。
+     *
+     * 注意 `ready` 也要走 `source !== next` 守卫：一个被换掉的旧连接可能在关掉之前
+     * 刚好把 ready 推过来，不挡就会把新连接的状态改成 open。
+     */
+    next.addEventListener('ready', () => {
       if (source !== next) return
-      attempt = 0
-      options.onStatus?.('open')
-      options.onOpen?.()
+      markOpen()
+    })
+    next.onopen = () => {
+      /* 响应头到了 ≠ 管道起来了：状态留在 connecting / reconnecting，等 ready 或第一行 */
     }
   }