@hyzyn/dsh-docker 0.4.0 → 0.5.0

package/README.en.md

@@ -0,0 +1,921 @@
+# @hyzyn/dsh-docker
+
+[中文](README.md) | English
+
+> The DSH sidebar "Containers" panel: containers on the local machine and on SSH hosts inspected on one screen — read logs, watch resources, enter containers, start / stop / remove, **Read-only by default**.
+
+## Features
+
+- **Many targets, one screen**: the "Overview" page fetches in parallel and one target failing does not affect the others; on the agent side `docker_ps target:'*'` gets the whole picture in one call.
+- **The "needs attention" criteria are accurate**: unhealthy / repeatedly restarting / **OOM-killed** / non-zero exit / zombie — OOM and the real exit code come from one `docker inspect` (a `ps` summary cannot tell whether 137 was an OOM kill or a manual kill).
+- **Four live SSE streams**: log FOLLOW, `docker stats`, `docker events` and `docker pull` share one piece of infrastructure (heartbeat / active-stream registry / teardown on disconnect); merged logs from a multi-select can be merged into one true timeline by timestamp, and "pause" is a real freeze.
+- **Read-only by default**: start / stop / remove, exec and image mutations all require switches explicitly enabled in settings; while they are off the tools are not registered and the routes return 403; passwords and passphrases are never sent back to the browser.
+- **tty is an optional partner**: with it installed there is an extra "Containers" button in the connection bar, SSH targets can reference connection-book entries directly, and cards gain a "Terminal" button that goes straight into the container; it also works without tty (degrading to copying the command).
+
+## Relationship with dsh-tty
+
+This plugin stands on its own: it imports no tty code, and tty needs no source changes; the two can be installed and upgraded independently. With tty installed they cooperate at the optional extension points below, and without it they degrade quietly.
+
+| Dimension | Description |
+| --- | --- |
+| Plugin form | A standalone package `@hyzyn/dsh-docker` that imports no tty code, and tty needs no source changes; the two can be installed and upgraded independently |
+| Connection book | SSH targets can **reference a tty connection-book entry name** (read-only access to `sshHosts` through `ctx.settings.get('tty')`); when tty is not installed this degrades to "inline host/username" or a local target |
+| Host fingerprints | This plugin keeps its own `hostKeys` (TOFU) and **prefers tty's already-recorded fingerprints as the seed** — the same host does not have to be confirmed in two places |
+| Execution channel | Its own pooled SSH exec (`src/ssh-exec.ts`), fully independent of tty's PTY sessions; neither takes the other's slots |
+| Context entry point | With tty ≥ 0.13.0 it can optionally consume tty's client service `ttyConnbar` and insert a "Containers" button in the SSH connection bar (next to SFTP) (**shown as soon as it is registered**), with the target resolved from the current session at click time; if tty is missing or too old this is skipped silently |
+| Panel hosting | With tty ≥ 0.16 and the terminal panel open, the container panel is **docked to the right of the terminal** via `ttyPanel.mountPane` (resize / collapse / ✕ provided by tty) while the terminal stays visible and usable; otherwise it falls back to a full-screen modal with its own backdrop. The panel itself is the same component, only the host differs. The dock holds one panel at a time: when this plugin docks it takes down the previous one (for example tty's own SFTP), and conversely SFTP falls back to its own dialog when the mount slot is already taken |
+| Terminal hosting | Interactive terminals are hosted by tty (it owns the PTY): with tty ≥ 0.15 they are **embedded in place** into the terminal drawer at the bottom of this panel via `ttyTerminal.mount` (in dock mode this becomes a **new tab** in the same panel, avoiding a terminal inside a panel inside a terminal); with tty ≥ 0.14 it falls back to "open a tab + collapse this panel"; with neither it copies the command. This plugin implements no PTY / xterm / reconnect stack |
+| Division of labour | **Interactive troubleshooting** (`docker exec -it`, a shell inside the container, TUIs) is hosted by tty (embedded drawer or tab); **read-only inspection and agent automation** use this plugin's own exec channel |
+
+Reuse at the data level without coupling at the code level: the connection book and the fingerprint seed are "reading the same settings", and the connection-bar button is "consuming a generic extension point" — neither is "depending on tty's modules", so upgrading or uninstalling tty does not break this plugin along with it.
+
+## Installation
+
+```bash
+dsh plugin --profile web add @hyzyn/dsh-docker              # npm install (once published)
+dsh plugin --profile web add link:$(pwd)/packages/docker    # repo development and debugging
+```
+
+The aggregate package `@hyzyn/dsh-all` (or the repo-root bundle) already includes this plugin, so there is no need to
+add it separately when installing everything at once. After installing, restart `dsh web` and the "Containers"
+entry appears in the sidebar; the Settings → Plugins →
+"Docker Container Panel" card maintains targets and switches, and **saving applies hot** (`settings/updated`
+triggers re-resolution, with no restart needed).
+
+> If you have already installed `@hyzyn/dsh-all` or the root bundle in the web profile, do **not** add this package
+> again, or the plugin line is mounted twice and startup reports `duplicate loader entry id`.
+
+## Usage
+
+Two entry points, one panel:
+
+- **Sidebar “Containers”** (the main entry point): works for any target, including local docker and switching between multiple targets.
+- **SSH connection bar "Containers" button** (a contextual shortcut, tty ≥ 0.13.0): in an SSH tab of the tty
+  terminal panel a "Containers" button appears next to the connection bar's SFTP button — **shown as soon as it is
+  registered**, and clicking it opens the panel directly on **the host of the current session**, with no target to
+  pick. The target is resolved at click time: when the session comes from the connection book it matches by entry
+  name, otherwise it matches a resolved target by `host:port`; **no matching target does not hide the
+  button** — the panel carries a hint naming the session host (including the connection-book name) and how to
+  configure it in the settings card.
+
+  ![docker panel docked to the right of the terminal panel: the terminal stays visible and usable](https://cdn.jsdelivr.net/gh/hyzyn/dsh-plugin-kit@main/docs/dsh-plugin-kit-docker-dock.png)
+
+  A panel opened this way **never covers the terminal**: with tty ≥ 0.16 it docks to the right of the terminal
+  panel (draggable width, collapsible into a narrow strip, ✕ to tuck away) while you keep typing in the terminal;
+  only with an older tty or no open panel does it fall back to the full-screen modal. In dock mode the card's
+  "Terminal" button instead **opens a new tab in the same terminal panel** running
+  `docker exec -it` (the panel is already inside a terminal, so nesting one more layer makes no sense); it also
+  **stops rendering the panel's own header** — the title and ✕ are handled by the sidebar title bar, and the
+  refresh control and read-only badge move to the
+  **end of the toolbar, right-aligned** (while refreshing the icon spins itself, with no extra spinner): the left
+  end stays for the target / view / search / filter controls, so refresh is not mistaken for the first filter and
+  sits where it does in the non-dock header; a 520px narrow column does not leave a blank line behind.
+
+Inside the panel:
+
+![Container list: target picker / search and state filtering / card action bars (the view and mutate groups)](https://cdn.jsdelivr.net/gh/hyzyn/dsh-plugin-kit@main/docs/dsh-plugin-kit-docker-panel.png)
+
+- **Switching targets has a transition and guards**: as soon as the picker changes, the cards below are still the
+  previous target's (a remote round trip can take up to 20s). Three principles for the transition layer —
+  **no layout shift, a sense of direction, little grey**:
+  - a 2px **indeterminate shimmer progress bar** (absolutely positioned) along the top of the panel body gives a
+    global "fetching" signal;
+  - a **blue capsule floats up centred** at the top of the body (the same placement and colour language as the
+    dsh-rss loading capsule): background `color-mix(accent 12%, surface)`, border `accent 42%`, text and spinner in
+    `--dk-accent`; the visible copy is just two segments, `⟳ Switching to Target2 · Currently showing: Target1`
+    (not written as a sentence, no quotes around target names), while the full "why won't it respond" story lives in
+    `title`, available on hover;
+  - old data stays at **82% + slight desaturation** (not dimmed into illegibility) and **the pointer is locked**: it
+    reads as "a different batch of content" rather than "it broke", and it also prevents acting on the stale list —
+    that would aim at the new target while sending commands with container IDs from the old list and really could
+    stop a same-named container on the other side;
+  - new data lands with an **8px slide-up + fade-in** over 200ms, so that "a different batch" is visible; the motion
+    respects `prefers-reduced-motion`.
+
+  Everything above is **absolutely positioned**: during a switch the first card's position and the scroll height
+  provably do not change at all (a banner approach would push the whole block of content down). **A failed switch
+  clears the old list** and settles into the new target's error state (it does not keep showing another target's
+  data), and the empty-state copy distinguishes "failed to read" from "filtered too narrowly".
+- **Target selection**: the panel picks a target first (from the `targets` config, local / SSH); with only one
+  target configured it is selected by default, and agent tools may also omit the `target` parameter.
+  **The last selected target is remembered** (stored in the browser's `localStorage` under
+  `dsh-docker:last-target`, not written to config or settings): the next time the panel opens it is selected
+  automatically. The priority is **what the connection bar specifies > last remembered (and still present) >
+  first in the list** — once the remembered target is deleted or renamed it falls back to the first one instead of
+  resting on an "unknown target"; when entering from the terminal connection bar's "Containers" button, the current
+  session host takes priority over the remembered value. Switching targets is **a whole-context switch**:
+  requests still in flight for the previous target are all invalidated (a list write gate), so there is no
+  cross-talk like "the picker is already Target2 while the cards are still Target1's containers", and an old
+  target's timeout banner does not linger on the new target's page.
+- **Multi-target Overview (read-only)**: the `Overview` pill next to the target picker (shown only with ≥2 targets
+  configured) — pick no target and see every host on one screen: a row of **counter cards** on top
+  (target name + a local / SSH marker + running / stopped / unhealthy), and below it a **table of containers needing
+  attention pinned to the top** (container / target / status / image; unhealthy sorts before restarting, ties follow
+  the targets' order in config, and rows do not jump between polls). Fetching is **parallel + progressive**:
+  each target issues its own `POST /containers` (`all:true`, since a bare `docker ps` does not return exited
+  containers and "stopped" would always be 0), and an unreachable target affects only its own cell — the card
+  outlined in red plus an "N targets unreachable" banner at the top, while the other targets' results show as usual
+  (deliberately **not** aggregated with `Promise.all`: an unreachable SSH host waits out the 20s readyTimeout, so
+  aggregating would keep the whole page silent for 20s). Clicking a counter card returns to that target's normal
+  container list, and clicking an attention row opens that container's details (going back lands on **that
+  target's** container list); **the Overview performs no cross-target operations**, and the attention table's rows
+  have no action buttons. Entering the Overview clears the failed banner left over from "the current target": the
+  Overview attributes everything per target (red card + unreachable banner) and no longer stacks a single-target
+  "operation failed" — the same SSH timeout told twice looks like two dead machines. Polling reuses the toolbar's
+  "auto refresh" switch (off by default): each round of this page is one `docker ps` per target across all N
+  targets, more expensive than any single-target page. With no exceptions it shows
+  "all good"; while some targets have not finished answering, the attention area shows "reading…" and
+  **that counter card also enters its loading state** (spinner + dimmed, no 0/0/0 — "0 containers" would be read as
+  "this machine has no containers" when it simply has not answered yet) ("don't know yet" is not "all good").
+- **Container list**: name / status / health / image / port mappings / compose project and service /
+  short ID; it supports **search** by name or image, **filtering** by state (running / stopped / all),
+  and **auto refresh** (polling at `pollIntervalSec`; switching to the images page pauses it and hides that
+  switch — images change slowly, so there is no point running `docker images` every 5s; switching back to the
+  containers page restores the previous setting). In the toolbar "include stopped" and "auto refresh" are two
+  **grouped** switches, and the search box is the only flexible item among them: on a wide panel the whole toolbar
+  collapses into one row, and only in a narrow column (dock, 520px) does it wrap by group — no orphan row holding a
+  single checkbox.
+- **"Activity" strip (the docker events stream)**: a collapsible narrow bar at the head of the container list
+  (expanded by default) that follows one SSE stream (`GET /api/dsh-docker/events/stream`, where the server runs
+  `docker events --filter type=container`) showing the last 8 events (time + container name + action, with `die`
+  carrying its exit code such as `die(137)`). It is the entry point for **event-driven refresh**: 500ms
+  **after an event arrives** it debounces a list refetch (not one request per frame), layering on top of the
+  existing `AUTO REFRESH` rather than excluding it — polling is the safety net, events cover "just happened". Events
+  stay in memory only (a ring buffer of 50), switching pages closes the stream, and switching targets clears the
+  buffer. The allowlist keeps only the nine lifecycle actions (start / die / stop / kill / oom /
+  health_status / destroy / rename / update): noise such as `exec_*` and `archive-path` (`docker cp`)
+  is dropped server-side — on one batch machine 47 events over 24 hours were all exec with 0 allowlist hits, so on
+  machines that are only ever exec'd the Activity strip is empty, and that is deliberate.
+- **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
+  start / stop / remove), and an action bar appears between the toolbar and the list: "N containers selected" +
+  `merged logs` + `Cancel`. `merged logs` needs at least 2 containers; at 7–8 selected it gives a soft hint
+  (browsers limit same-origin concurrent long connections), and above **8** the button is greyed out with a hint
+  about the cap. Clicking `merged logs` opens the merged view: it reuses exactly the merged logs of the Compose
+  project view (one `/logs/stream` per container, mixed by the `[service]` / container-name prefix, with filtering
+  and auto-scroll), and going back exits selection mode and clears it.
+  Clicking `Select for merging` again or pressing **Esc** likewise exits and clears. Selection is **temporary**:
+  not persisted, not named into groups, not written to settings; it is dropped when switching targets / switching
+  the "Containers · Images · Compose" segment / closing the panel, and containers that disappeared after a list
+  refresh are pruned by id.
+- **One-click selection by condition** (in selection mode): the action bar's second row offers a row of condition
+  chips (`all visible / unhealthy / needs attention / stopped`, plus `same image / same project` once something is
+  selected), with counts **truncated to the remaining slots** — a chip reading 8 really does select 8; anything over
+  the cap is stated honestly in the title and the result hint. Conditions only apply within the
+  **current filtered result** (search / filter the state first, then select in one click).
+- **Container cards**: "label + value" rows matching the reference layout (image / ID / ports / created /
+  compose, with monospaced truncatable values) plus a row of icon action buttons, **split by a vertical rule into
+  the "view / mutate" groups**:
+
+  | Group | Buttons | Description |
+  | --- | --- | --- |
+  | View / enter | Terminal, logs, resource usage | Does not change container state; always available even in read-only mode |
+  | Mutate | start / stop, restart, remove | Ordered by increasing destructiveness; available only with `allowMutations` on, otherwise the whole group is greyed out |
+
+  Remove gets two extra protections: destructive colouring plus a gap between it and "restart", and a second
+  confirmation after the click. **The whole group is locked while a command is in flight**: `stop` / `rm` waits for
+  the container to actually exit (up to a dozen seconds), during which the confirmation dialog stays open showing
+  "running…" (both buttons disabled), the card's other mutate buttons are dimmed and greyed, the icon that is running
+  becomes a spinner, and everything is restored only once the refreshed list lands — preventing rapid clicking from
+  stacking mutually interrupting commands such as stop + restart + remove. Image removal / pruning goes through the
+  same confirmation dialog and also has a running state. Clicking a card body opens the overview.
+- **Container details (a full-column view)**: the top is "back + container name + status badge + target host",
+  with three tabs below — overview (`docker inspect` authoritative data + one-shot exec), logs and
+  stats. The log / stats icons on a card land directly on the corresponding tab.
+- **Log view (a compact two-row layout)**: the first row = back + container name + status + target host +
+  `LINES` (tail line count) / `TIMESTAMPS` / **`FOLLOW` (live follow, see below)** /
+  `AUTO REFRESH` (a switch plus 2/3/5/10s intervals, polling on the log page only) + refresh / download / close;
+  the second row = the tabs + an **always-present** "filter logs"
+  input (a fixed slot on the right shows "N lines" / "N / M lines matched"; when it has content an ✕ floats inside
+  to clear, and Esc clears too). The input's width and position never change, so typing or clearing never nudges
+  this row. The log body is coloured by level (both common prefixes, `[INFO]` and `|INFO`,
+  are recognised), timestamps are dimmed, and filter hits are highlighted; beyond 2000 lines only the tail is
+  coloured, with a hint. In the details view the list toolbar and panel header are no longer layered on top, so
+  each screen has exactly one refresh entry point.
+- **FOLLOW live log stream**: with the log page's `FOLLOW` switch on, the UI switches from "polling a snapshot" to
+  **SSE push** (`GET /api/dsh-docker/logs/stream`, where the server runs
+  `docker logs --follow`) — new log lines are appended as they arrive and polling stops; `FOLLOW` and
+  `AUTO REFRESH` are mutually exclusive (opening the stream stops polling and greys out the switch), and closing it
+  returns to snapshots with an immediate refresh. Streaming logs keep the last **5000 lines** (a ring buffer that
+  drops the oldest and hints once); filtering / level colouring share exactly the same rendering as snapshots. It
+  auto-scrolls to the bottom, pauses when the user scrolls up and floats a
+  "back to bottom" button; a status line in the top right shows the connection state, a browser disconnect is
+  auto-reconnected by EventSource (updating only the status, without an error banner), and a stream that ends
+  naturally because the container exited switches back to snapshot refresh automatically.
+  Connecting / switching pages / closing the panel all close the `EventSource`.
+- **Overview**: `docker inspect`'s authoritative data — state and health, exit code, restart count and policy,
+  port mappings, mounts (including read-only flags), networks and IPs, entrypoint and command, and the latest
+  health-check output; below it you can run a one-shot `docker exec` (requires `allowExec`).
+- **Logs**: a tail snapshot from `docker logs --tail` (`logTailDefault` lines by default), with timestamps and
+  `--since` switchable; output beyond `maxOutputKb` is truncated and marked. To keep watching new logs, turn on
+  `FOLLOW` above (the same argv plus `--follow`, with no overall timeout and no output cap, ending on the
+  connection's lifecycle).
+
+![Log page: level colouring + an always-present filter box + line counts](https://cdn.jsdelivr.net/gh/hyzyn/dsh-plugin-kit@main/docs/dsh-plugin-kit-docker-logs.png)
+- **Stats**: a `docker stats --no-stream` snapshot (CPU% / memory usage and share / network IO /
+  block IO / PIDs), refreshed by the panel at `pollIntervalSec`. The stats page also has **`FOLLOW` live
+  following**: turning it on switches to `GET /api/dsh-docker/stats/stream` (the server runs **without**
+  `--no-stream` for `docker stats`, one line per second), and the browser side keeps a **60-point ring
+  buffer** to draw CPU / memory **mini trend charts** (sparklines). Unlike the log stream, this one **does not end
+  naturally**; its close semantics are the frontend actively aborting the `EventSource`, and when `docker stats`
+  exits by itself the server sends `end` (reason=`stats-exit`), whereupon the UI hints and switches back to snapshot
+  polling.
+- **Compose project view**: the toolbar's third segment. It groups the `composeProject` / `composeService`
+  labels into "project → service → container", one row per project showing the running / unhealthy / service counts
+  and each container's state; clicking into a project shows the service table, or opens **project-level merged
+  logs** — one `/logs/stream` per container in the project, mixed client-side by the `[service]` prefix (the
+  host-side `logsStream` already supports arbitrary containers, so no new endpoint is needed), with an auto-scroll
+  switch and a filter box. Merging follows arrival order and does not guarantee strict cross-container ordering.
+- **Images**: a `docker images` list (reference / size / created / short ID);
+  `<none>:<none>` dangling images carry a `dangling` marker. The search box and the "N / M images"
+  counter are **fixed in the toolbar** (they do not scroll away with the list), and the header column names stick
+  within the table body. Each row has two actions, "details / remove": **details** opens the full-column view
+  (overview: size / size including parents / created / platform / layers / entrypoint and command / exposed ports /
+  digest / labels; build history: the per-layer commands and sizes from `docker history`). **Remove** (requires
+  `allowMutations`) runs `docker image rm` after a second confirmation (**without** `-f`, so an image that is
+  referenced fails with a hint to "remove the related containers first").
+- **Networks / volumes (the fifth and sixth segments)**: the toolbar segments extend to "Containers / Images /
+  Compose / Networks / Volumes" (when a narrow column cannot fit them, the segment container scrolls horizontally
+  by itself, with no second-level menu). Both pages use the same "table + full-column details" layout:
+  - **Networks**: name / driver / scope / internal badge / ID, with a row click opening details — overview
+    (ID / driver / scope / created / subnet / gateway / internal·attachable·ingress·ipv6 / options / labels) and a
+    "connected containers" tab (container / IPv4 / IPv6 / MAC). **Container counts deliberately stay out of the
+    list rows**: only `docker network inspect` returns the connected list, and inspecting every row would be N
+    docker calls, so it is fetched once on entering details instead.
+  - **Volumes**: name / driver / scope / mountpoint (over-long paths are width-limited and truncated, with the full
+    value in title); details are name / driver / scope / mountpoint / created / options / labels (volumes have no
+    reverse index, so there is only the overview page).
+  - The details header has a **remove** button, and both toolbars have a **prune icon**, all gated by
+    `allowMutations` (greyed out with an explanatory title when off) and all requiring a second confirmation; a
+    failed removal (a network still has containers attached / a volume is still in use / 403) shows an inline banner
+    on the details page rather than failing silently.
+  - Auto refresh matches the images page: these two pages **do not poll** (inventories change slowly, and a `docker`
+    CLI call every 5s is burnt for nothing); they refresh only when switching pages or targets.
+- **Pulling images (an SSE progress stream)**: the pull icon in the images toolbar (requires `allowMutations`)
+  opens the pull view; after entering a reference it goes through `GET /api/dsh-docker/images/pull/stream`
+  (where the server runs `docker pull`) — per-layer progress (Pulling fs layer / Downloading /
+  Extracting / Pull complete) appears live; progress lines are updated in place keyed by "layer key", and TTY `\r`
+  refreshes do not make the buffer grow ever longer. The toolbar's "prune dangling" runs
+  `docker image prune -f`, which **only removes untagged images** (deliberately without `--all`, to avoid
+  deleting ordinary unused images by mistake).
+
+![Images page: the search box is fixed in the toolbar and the header sticks](https://cdn.jsdelivr.net/gh/hyzyn/dsh-plugin-kit@main/docs/dsh-plugin-kit-docker-images.png)
+- **One-shot exec**: with `allowExec` on you can type a command, equivalent to
+  `docker exec <container> sh -c "<command>"`, returning the exit code and stdout/stderr (no TTY).
+- **Interactive terminal (the first icon on a card)**: it runs `docker exec -it '<container>' sh`. It degrades in
+  three steps depending on tty's capabilities —
+  ![exec terminal drawer coexisting with the log page: collapsing only hides it, the session keeps running](https://cdn.jsdelivr.net/gh/hyzyn/dsh-plugin-kit@main/docs/dsh-plugin-kit-docker-exec.png)
+
+  1. **Embedded in place (tty ≥ 0.15, recommended)**: a **terminal drawer** opens at the bottom of the panel, and
+     tty's `ttyTerminal.mount` mounts the terminal into it. The panel does not collapse, so you can watch the
+     container's logs and step into the container to type commands without losing context. The drawer takes height
+     away from the body, so it can give way without ending the session:
+     **collapsing** (the arrow at the right of its title bar, or double-clicking its top edge) squashes the drawer
+     into one title bar while the session keeps running; **dragging the top edge** resizes it (capped at 75% of the
+     panel height). Only two actions really end a session — the ✕ on the drawer and closing the panel; with an
+     active session, closing the panel asks for confirmation first, so that clicking the blank backdrop does not
+     kill a container shell that is mid-troubleshooting (the global terminal panel also treats "clicking the blank
+     area = minimize", the same stance).
+  2. **Open a tab through tty (tty ≥ 0.14)**: tty opens a new tab running the same command, and this panel then
+     collapses (this panel has a higher z-index, so not collapsing would only make the user feel "nothing
+     happened").
+  3. **Copy the command**: when tty is not installed / too old / an inline target uses key·password auth (the
+     browser has no credentials), it degrades to copying the command with a hint to paste it into the terminal
+     panel.
+
+  Local targets open a local session, while SSH targets go over SSH by connection-book entry name (or by the inline
+  fields authenticated by the agent), and the tab / drawer title is `<container> · exec`. Capability detection goes
+  through the service contract version (`mount` exists only with `ttyTerminal.version >= 2`), not by guessing
+  whether a function exists.
+
+
+### Targets (local / SSH)
+
+| `kind` | Description |
+| --- | --- |
+| `local` | the docker CLI on the machine hosting the plugin (`spawn` runs it directly, not through a shell) |
+| `ssh` | connects to a remote host over `ssh2` and runs the docker CLI remotely (argv single-quote escaped) |
+
+There are two ways to fill in `kind=ssh`:
+
+1. **Reference a tty connection-book entry**: put the entry name in `book` (maintained in the connection book
+   under Settings → Plugins → Terminal Panel), and the host / port / username / auth method follow from it. The
+   settings card's dropdown only lists connection-book entries tty has saved; if tty is not installed or the entry
+   does not exist, that target fails to resolve and both the panel and the agent tools report a clear error.
+2. **Inline fields**: `host` + `username` are required, the rest as needed (`port` / `auth` /
+   `keyPath` / `password` / `passphrase` / `agentForward`).
+
+Targets are resolved **fresh for every operation**: if you change a connection-book entry in the tty card (a
+different port, a new password), the next operation uses the new value immediately with no restart. The remote side
+must satisfy: the docker CLI is installed, and the current account can use docker
+**without sudo** (usually because it is in the `docker` group); otherwise `probe` passes through errors such as
+`permission denied while trying to connect to the Docker daemon socket` verbatim.
+
+### Merged logs (multi-select / Compose project)
+
+Selecting several containers or opening a Compose project can both merge the logs of several containers into one
+stream (one `docker logs -f` SSE per container, mixed client-side in arrival order). The toolbar offers:
+
+| Control | Semantics |
+| --- | --- |
+| **Live / Paused** | a real pause (see below) |
+| **Timestamps** | shows a timestamp on every line. Timestamps are **always received with the stream** (`timestamps=1`); this only affects display |
+| **By arrival / By time** | `by arrival`: follows with zero delay; `by time`: merges into one true timeline using each line's container timestamp |
+| **Level filter** | `all levels / WARN+ / ERROR+`. **Lines with no level prefix (continuation lines such as stack traces) inherit the level of the previous log entry**, so ERROR+ keeps its stack trace with it and INFO continuations are filtered out together with their first line; orphan continuation lines at the start of the window (whose record header is outside the window) cannot be judged and are kept |
+| **⬇ .log / ⬇ .md** | exports what is currently displayed: `.log` is plain line text (`[service] ISO time body`), while `.md` carries a header with the source containers / line count / export time and can be attached to a ticket directly |
+
+**How merging by time works**: the SSE connections for the various containers are established at different moments,
+so A's initial backlog may arrive in one batch while B's arrives later, and sorting each batch on its own cannot fix
+cross-batch inversions. The implementation **backfills the last 400 lines** — whenever a new batch of lines arrives
+it re-sorts "the last 400 lines + the new lines" by timestamp (using the RFC3339 prefix from
+`docker logs --timestamps` as the sort key, which is parsed and then stripped from the body). That way it neither
+stalls for a while to get the first screen right (no one-second blank page on open) nor fails to correct historical
+misordering after the fact; the price is that in "by time" mode the last few lines already on screen may shift
+slightly (use "by arrival" while following live output).
+
+### "Pause" in merged logs (a real pause)
+
+The merged logs of a multi-select / Compose project have a `Live / Paused` switch. **Pausing freezes the content**,
+not just auto-scroll:
+
+- while paused, newly arriving logs go into a client-side buffer and **the DOM is no longer appended to** — the
+  screen reader is not pushed away, and the view does not jump when the display cap (2000 lines) trims the front;
+- the button itself shows how many lines have accumulated (`Paused +348`);
+- on resume the buffer is merged in one go (still under the 5000-line ring cap) and the view returns to the bottom.
+
+Only stopping auto-scroll is not enough: with the label saying "paused" while the content keeps growing, users think
+the switch is broken; and with a high log volume the view also jumps by itself as the front is trimmed.
+
+### Overview (cross-target) and the "needs attention" criteria
+
+The "Overview" page lays out all targets on one screen: one counter card per target (running / stopped / unhealthy /
+**needs attention**), and below it a cross-target "containers needing attention" table (container / target / status /
+**reason** / image; click a row for details, click a card to switch to that target's list). Three design constraints:
+
+- **Progressive landing + failure isolation**: each target requests and lands independently; one unreachable SSH host
+  does not silence the whole page — the unreachable target gets its own banner and the other targets' results remain
+  available.
+- **The "needs attention" criteria are the host's**: the container list and `/attention` are requested in parallel;
+  the latter does an extra `docker inspect`, so it can identify **OOM (OOMKilled)** and the **real exit code** — a
+  `ps` summary's `Exited (137)` cannot tell an OOM kill from a manual kill. When `/attention` is unavailable (an
+  older host / that target failed) it falls back to the summary criteria and labels the count
+  "needs attention (rough)".
+- **Ordering**: OOM > zombie > unhealthy > repeatedly restarting > non-zero exit; equal weights are ordered by
+  "most recent end time" descending, so the freshest crash is at the top (hovering a row shows the end / start times,
+  restart count and exit code).
+
+## Configuration (Settings → Plugins → "Docker Container Panel", saved and applied hot)
+
+![Settings card: target CRUD, capability switches and parameters, saved and applied hot](https://cdn.jsdelivr.net/gh/hyzyn/dsh-plugin-kit@main/docs/dsh-plugin-kit-docker-setting.png)
+
+Configuration lives in the settings namespace `docker`, i.e. the `docker:` section of `~/.dsh/settings.yaml`
+(`$DSH_HOME/settings.yaml`; DSH's settings file is provided by the host's `dsh-settings-file`). The composition
+config in the plugin line acts as the schema's `base`, which the settings layer overrides; the HTTP
+`POST /api/dsh-docker/config` is the card's write channel and accepts only the keys in the table below (unknown keys
+return 400).
+
+| Item | Default | Description |
+| --- | --- | --- |
+| `enabled` | true | disables the whole plugin (**takes effect after restarting `dsh web`**, same semantics as tty) |
+| `announceToAgent` | true | whether to inject a capability announcement into the agent (systemPrompt section `plugin:dsh-docker`) |
+| `dockerBin` | `docker` | the docker CLI executable name or path (`podman` works here); only letters, digits and `_ . / -` are allowed |
+| `allowMutations` | false | allows **mutating operations**: container start / stop / restart / remove, image removal / dangling pruning / pulling (the panel buttons and the `docker_action`, `docker_image_remove`, `docker_image_prune`, `docker_image_pull` tools; while off, `/action`, `/images/remove`, `/images/prune`, `/images/pull/stream` return 403 and the corresponding tools are not registered) |
+| `allowExec` | false | allows a one-shot `docker exec` (the panel's exec input and the `docker_exec` tool; while off, `/exec` returns 403) |
+| `execTimeoutSec` | 30 | default exec timeout in seconds (1–120) |
+| `pollIntervalSec` | 5 | stats refresh interval for the panel, in seconds (1–60) |
+| `logTailDefault` | 200 | default log tail line count (1–5000) |
+| `maxOutputKb` | 512 | output cap for a single command (KB, 1–8192); anything beyond is truncated and marked `truncated` |
+| `targets` | `[]` | target list, see below |
+| `hostKeys` | `[]` | SSH host fingerprint records (TOFU, maintained automatically) |
+
+Out-of-range numbers are clamped to the boundary, and a value of the wrong type falls back to the default.
+
+### `targets[]` fields
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `name` | — (required) | the target's display name, unique; empty or duplicate entries are dropped on save (≤64 characters) |
+| `kind` | `local` | `local` for this machine / `ssh` for remote |
+| `book` | `''` | with `kind=ssh`, references a tty connection-book entry name (leave empty to use the inline fields below) |
+| `host` | `''` | inline hostname or IP (required when there is no `book`) |
+| `port` | 22 | SSH port (1–65535, out of range falls back to 22) |
+| `username` | `''` | inline SSH username (required when there is no `book`) |
+| `auth` | `agent` | `agent` (uses `SSH_AUTH_SOCK`) / `key` (uses `keyPath`) / `password` (uses `password` and also attaches keyboard-interactive) |
+| `keyPath` | `''` | private key path for `auth=key` (a leading `~` expands to home) |
+| `password` | `''` | password for `auth=password`; **prefer `env:VAR`** to reference an environment variable |
+| `passphrase` | `''` | private key passphrase; **prefer `env:VAR`** to reference an environment variable |
+| `agentForward` | false | whether to forward the local ssh-agent (takes effect when `SSH_AUTH_SOCK` exists) |
+
+An `env:VAR` inside `password` / `passphrase` is resolved only when connecting (`process.env[VAR]`), and a missing or
+empty variable reports `环境变量未设置: VAR` ("environment variable not set: VAR") explicitly. These two values are **never sent back to the browser**:
+the config snapshot only provides the two booleans `passwordSet` / `passphraseSet`.
+
+### `hostKeys[]` (SSH host fingerprints, TOFU)
+
+| Field | Description |
+| --- | --- |
+| `host` | hostname or IP (required) |
+| `port` | port, default 22 (unique per host:port) |
+| `fingerprint` | the verbatim hex fingerprint received by the `hostHash: 'sha256'` callback (required) |
+
+The first connection is recorded automatically and written to disk; every later connection must match, and
+**a changed fingerprint rejects the connection outright**, with guidance in the error to "delete this host's record
+and reconnect". The record list can be deleted / reset in the settings card.
+
+## Agent tools
+
+| Tool | Registration | Parameters | Purpose / typical use |
+| --- | --- | --- | --- |
+| `docker_targets` | always registered | `probe?: boolean` | lists targets (name / kind / label); `probe:true` probes the docker version and daemon reachability for each one (SSH targets open connections, so it is slower). Other tools take their `target` from here |
+| `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`). 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_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 |
+| `docker_networks` | always registered | `target?` | network list (name / driver / scope / internal flag / short ID). The connected-container list stays out of the list rows — the details page does the inspect, whereas inspecting row by row would be N docker calls |
+| `docker_volumes` | always registered | `target?` | volume list (name / driver / scope / mountpoint) |
+| `docker_image_inspect` | always registered | `target?`, `ref` (required) | `docker image inspect` + `docker history`: size / size including parents / created / platform / layer count and layer list / entrypoint and command / exposed ports / digest / build history (each step's command and size) |
+| `docker_action` | only with `allowMutations` | `target?`, `action` (`start` \| `stop` \| `restart` \| `remove`), `id` | container lifecycle operations. `remove` is destructive: it deletes the container config and writable layer (data volumes are not included), and the target container must be confirmed with the user before running |
+| `docker_image_remove` | only with `allowMutations` | `target?`, `ref` (required) | removes an image (`docker image rm`, without `-f`). **Destructive**: it fails when the image is referenced by a container or a child image; confirm the target image and restate the consequences before running |
+| `docker_image_prune` | only with `allowMutations` | `target?` | prunes dangling (untagged) images (`docker image prune -f`). Deliberately without `--all`, so only untagged images go |
+| `docker_image_pull` | only with `allowMutations` | `target?`, `ref` (required), `timeoutSec?` (10–1800, default 600) | `docker pull` in snapshot form (**may take several minutes**); for interactive per-layer progress have the user watch the SSE progress stream from the pull icon on the panel's images page |
+| `docker_exec` | only with `allowExec` | `target?`, `id`, `command` (required, run through `sh -c` inside the container), `timeoutSec?` (1–120, default `execTimeoutSec`) | a one-shot `docker exec` returning the exit code / stdout / stderr; there is no TTY, so for interactive troubleshooting have the user run `docker exec -it <container> sh` in the tty panel |
+
+- When `target` is omitted it falls back to **the only** configured target; with several targets configured it is
+  required, and the error message lists the available target names.
+- Changing either switch **re-registers the tools immediately**: after turning off `allowMutations` / `allowExec`
+  the corresponding tools (including the three image mutation tools) disappear from the agent side, with no restart.
+- Recommended troubleshooting order: `docker_targets` → `docker_ps` → `docker_logs` →
+  `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
+  constraints "read-only by default" and "docker socket ≈ root on the target host"), so the model lists targets
+  before acting.
+
+## HTTP routes (under the `/api/dsh-docker` prefix, all behind the loopback fence)
+
+The fence validates `remoteAddress` (127.0.0.1 / ::1 / ::ffff:127.0.0.1), `Host`,
+`Origin` and `sec-fetch-site`; any non-local request gets 403 `forbidden: loopback-only`.
+The request body is capped at 1MB, and responses are uniformly `application/json` + `referrer-policy: no-referrer`.
+
+| 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` | 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?}]}` |
+| `/probe` | POST | `{target?}` | `{ok:true, probe:{ok, bin, serverVersion, error, target}}` |
+| `/containers` | POST | `{target?, all?}` | `{ok:true, containers: ContainerSummary[]}`; with `target:'*'` it returns `{ok:true, groups:[{target,label,ok,error?,data?}]}` (concurrent cross-target aggregation) |
+| `/attention` | POST | `{target?}` | for a single target `{ok:true, items: AttentionItem[]}`; with `target:'*'` `{ok:true, groups}` |
+| `/inspect` | POST | `{target?, id}` | `{ok:true, details: ContainerDetail[]}` |
+| `/stats` | POST | `{target?, ids?: string[]}` | `{ok:true, stats: ContainerStats[]}` |
+| `/logs` | POST | `{target?, id, tail?, timestamps?, since?}` | `{ok:true, logs:{id, text, truncated}}` |
+| `/logs/stream` | GET | query: `target?`, `id` (required), `tail?` (1–5000), `timestamps?` (`1`/`true`), `since?` | `200 text/event-stream` long connection, event protocol below; bad parameters / unknown target / non-loopback return ordinary JSON errors |
+| `/stats/stream` | GET | query: `target?`, `ids?` (comma-separated; omitted = all running) | `200 text/event-stream`: one `stats` frame per second (ContainerStats, same shape as the /stats snapshot); it does not end naturally and is finished off by the client disconnecting |
+| `/events/stream` | GET | query: `target?` | `200 text/event-stream`: one container event per `event` frame (already through the server-side allowlist, with missing-value fields omitted); it does not end naturally and is finished off by the client disconnecting |
+| `/images` | POST | `{target?}` | `{ok:true, images: ImageSummary[]}` |
+| `/images/inspect` | POST | `{target?, ref}` (required) | `{ok:true, image:{ref, detail: ImageDetail, history: ImageHistoryEntry[], historyError}}`; history prefers `--format '{{json .}}'` and falls back to a plain-text table on older versions |
+| `/images/remove` | POST | `{target?, ref}` (required) | requires `allowMutations` (otherwise 403); `docker image rm` (without `-f`); `{ok:true, result:{ref, message}}` |
+| `/images/prune` | POST | `{target?}` | requires `allowMutations` (otherwise 403); `docker image prune -f` (dangling only); `{ok:true, result:{message}}` |
+| `/images/pull/stream` | GET | query: `target?`, `ref` (required) | requires `allowMutations` (otherwise 403 and no stream is opened); `200 text/event-stream`: `line` per-layer progress + `end{reason:'pull-exit',code,ref}` |
+| `/networks` | POST | `{target?}` | `{ok:true, networks: NetworkSummary[]}` |
+| `/networks/inspect` | POST | `{target?, name}` (required) | `{ok:true, network:{name, detail: NetworkDetail}}` (subnet / gateway / options / labels / connected containers) |
+| `/networks/remove` | POST | `{target?, name}` (required) | requires `allowMutations` (otherwise 403); `docker network rm`; `{ok:true, result:{name, message}}` |
+| `/networks/prune` | POST | `{target?}` | requires `allowMutations` (otherwise 403); `docker network prune -f`; `{ok:true, result:{message}}` |
+| `/volumes` | POST | `{target?}` | `{ok:true, volumes: VolumeSummary[]}` |
+| `/volumes/inspect` | POST | `{target?, name}` (required) | `{ok:true, volume:{name, detail: VolumeDetail}}` (mountpoint / options / labels) |
+| `/volumes/remove` | POST | `{target?, name}` (required) | requires `allowMutations` (otherwise 403); `docker volume rm` (**the data goes with the volume**); `{ok:true, result:{name, message}}` |
+| `/volumes/prune` | POST | `{target?}` | requires `allowMutations` (otherwise 403); `docker volume prune -f` (**deletes data**, see known limitations); `{ok:true, result:{message}}` |
+| `/action` | POST | `{target?, action, id}` | requires `allowMutations` (otherwise 403); `{ok:true, result:{id, action, message}}` |
+| `/exec` | POST | `{target?, id, command, timeoutSec?}` | requires `allowExec` (otherwise 403); `{ok:true, result:{id, command, code, stdout, stderr, truncated, durationMs}}` |
+
+Any other sub-path is 404 (`unknown route: ...`); a GET on anything other than `/config`, `/targets` and the three
+`*/stream` routes above returns 405; an execution failure (a docker error, a target that fails to resolve, and so on)
+returns 500 or 400 plus an `{error}` text.
+
+### SSE event protocol (`/logs/stream`, `/stats/stream`, `/events/stream`, `/images/pull/stream`)
+
+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:
+
+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 |
+| --- | --- | --- |
+| `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) |
+| `end` | `{"reason":"container-exit"\|"stats-exit"\|"events-exit"\|"pull-exit","code":N, ...}` | the executor exited naturally. The log stream attaches the container's exit code, the stats stream has reason=`stats-exit`, the event stream reason=`events-exit`, and the pull stream attaches `ref` |
+| `error` | `{"message":"..."}` | a parameter / execution failure, after which the stream closes; a break at the connection layer does not send this event |
+
+The four streams differ only in "executor + end reason":
+
+| Stream | Executor | Natural end condition | Close semantics |
+| --- | --- | --- | --- |
+| `/logs/stream` | `docker logs --follow` | the container stops (`container-exit`) | the frontend turns FOLLOW off / switches pages / closes the panel |
+| `/stats/stream` | `docker stats` (**without** `--no-stream`) | all the containers being measured exit (`stats-exit`) | **the frontend aborts it** (this stream does not stop by itself) |
+| `/events/stream` | `docker events` (`--filter type=container`) | the daemon-side stream ends (`events-exit`) | switching pages / switching targets / closing the panel |
+| `/images/pull/stream` | `docker pull` | the pull completes / fails (`pull-exit`) | the frontend leaves the pull view |
+
+- Response headers: `content-type: text/event-stream; charset=utf-8`, `cache-control:
+  no-cache`, `connection: keep-alive`, with `flushHeaders()` immediately after writing them (the host's gzip
+  explicitly skips `text/event-stream`, so nothing is buffered).
+- Heartbeat: one `: ping` comment frame every 15s (ignored by clients per the SSE spec).
+- Teardown: the client disconnects → the executor is aborted immediately (locally `SIGTERM`, then `SIGKILL` if it has
+  not exited in 2s; over SSH that exec channel is closed and the pooled connection is kept for reuse), writing no
+  frame at all; the plugin is disabled / the config is hot-updated / it is uninstalled → the server wraps up on its
+  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.
+
+## Security model
+
+**The docker socket ≈ root on the target host.** Anyone who can reach the daemon can mount host directories, start
+containers in privileged mode and read the secrets inside containers — which is why this plugin is designed
+read-only first:
+
+1. **Read-only by default**. With `allowMutations` off, `/action`, `/images/remove`,
+   `/images/prune`, `/images/pull/stream` all return 403, the panel's start / stop / remove / image
+   removal / pruning / pulling are unavailable, and the `docker_action`, `docker_image_remove`,
+   `docker_image_prune`, `docker_image_pull` tools are **not registered at all**; with `allowExec`
+   off, `/exec` returns 403 and the `docker_exec` tool is likewise not registered. The two switches are
+   independent and must be turned on explicitly by the user in the settings card. Read-type routes (`/logs/stream`,
+   `/stats/stream`, `/events/stream`, `/images/inspect`) are unaffected by either switch.
+2. **Destructive operations restate their consequences**. `remove` maps to `docker rm` (**without `-f`**), and the
+   agent announcement requires confirming the target container with the user before running; a running container
+   errors with a hint that "the container is still running: stop it before removing", never a silent force-delete.
+3. **Credentials do not land in plaintext (recommended)**. `password` / `passphrase` support `env:VAR` references,
+   and hosting the secrets with dsh-env-manager avoids plaintext in `settings.yaml`; `agent`
+   auth (`SSH_AUTH_SOCK`) is not written to disk at all. The config snapshot only answers "is it set".
+4. **Host fingerprint TOFU pinning**. The first connection records the sha256 fingerprint; every later one must
+   match, and a change rejects the connection (MITM protection); a host tty has already confirmed is trusted directly
+   as a seed and copied into this plugin's records. TOFU's inherent limits are that "if the first connection already
+   met an MITM, what got recorded is a fake fingerprint", and that only one record is kept per host:port (multiple
+   key types on the same host may report a change incorrectly; deleting the record and reconnecting re-calibrates
+   it).
+5. **Commands are always built as argv, never by string concatenation**. Container names / IDs first pass the
+   `assertRef` allowlist (`[A-Za-z0-9][A-Za-z0-9_.-]*`, ≤128 characters, rejecting spaces, `;`,
+   `$()`, backticks and so on), and image and container references likewise; remotely each argument is single-quote
+   escaped by `shJoin` before being handed to the remote shell, while locally `spawn(bin, args)` goes through no
+   shell.
+6. **Output is capped**. `maxOutputKb` limits the stdout/stderr bytes of a single command; anything beyond is
+   truncated and marked, so large logs cannot blow up memory or the agent's context.
+7. **HTTP is exposed to this machine only**. All routes go through the loopback fence, so a remote browser cannot
+   call them.
+8. **The live log stream is a read-only capability**. `GET /logs/stream` matches `/logs`: it is not gated by
+   `allowMutations` / `allowExec` (it does not change container state), but it likewise admits loopback only, passes
+   `id` through the `assertRef` allowlist and clamps parameters the same way. Unlike a snapshot, a long stream has no
+   `maxOutputKb` cap (following would lose its point if truncated), and memory protection is shouldered by the
+   client's 5000-line ring buffer and 2000-line colouring cap.
+
+## Known limitations
+
+- **No interactive TTY**: `exec` is a one-shot command (`docker exec <id> sh -c <cmd>`,
+  without `-i` / `-t`), so it cannot run vim / top / an interactive shell, nor feed stdin for a
+  dialogue. For interactive troubleshooting run `docker exec -it <container> sh` in the tty panel (this works for
+  both local and SSH targets).
+- **The event stream has a window while disconnected**: `docker events` is a stream of "from now on", so events that
+  happen while the browser is disconnected and reconnecting have already been pushed by the server and are not
+  resent. The client compensates with "do a full list refresh right after a successful reconnect"
+  (aligning state, not replaying the events); the few entries missing from the Activity strip can only be inferred
+  from the final state after that refresh. For an exact, complete event history use the `docker_events` tool (a
+  snapshot with `--since`).
+- **The four boundaries of streaming**: the log page's `FOLLOW` (SSE + `docker logs -f`), the stats page's
+  `FOLLOW` (SSE + `docker stats` + a 60-point sparkline), the container list's event stream
+  (SSE + `docker events`, driving the Activity strip and the debounced list refresh), and the images page's pull
+  progress stream (SSE + `docker pull`); but the agent tools `docker_logs` / `docker_stats` /
+  `docker_image_pull` all keep **snapshot semantics** (a single-value return model does not suit an unbounded
+  stream). Streaming logs keep only the last 5000 lines on the browser side (dropping the oldest, with a hint), and
+  stats keep only 60 samples.
+  A long SSH stream holds that connection in the pool (busy) while other commands on the same host still reuse the
+  same connection without affecting each other. **The stats stream does not end naturally**, so closing it must be
+  the frontend actively aborting the `EventSource`.
+- **Docker CLI version differences**: parsing goes through `--format '{{json .}}'`, and fields come and go between
+  versions; the parser always degrades instead of throwing (for example, a missing `State` has the state derived from
+  `Status`, and health is extracted from `(healthy)` / `(unhealthy)`); with fields missing the corresponding columns
+  may be empty, so use the details (`docker inspect`) when you need authoritative data.
+- **`rm` without `-f`**: container `remove` maps to `docker rm` and image `remove` to
+  `docker image rm`, neither with `-f` — a running container, or an image referenced by a container or a child
+  image, fails with a hint; to force deletion, run it by hand in the tty panel.
+- **SSH targets need sudo-free docker**: if the account is not in the docker group, docker reports a permission
+  error which the panel and the tools pass through verbatim, without attempting automatic sudo escalation.
+- **Docker not installed on the remote**: `probe` fails (`command not found` / exit code 127) and the panel shows
+  the error; when PATH differs, fill `dockerBin` with an absolute path.
+- **Podman compatibility through `dockerBin`**: filling in `podman` runs, but the fields and output formats of
+  `stats` and `--format '{{json .}}'` differ from docker's, so only the parser's degradation paths are relied on;
+  this has not been verified item by item.
+- **No image builds / Compose orchestration changes**: images support pulling / removal / dangling pruning, but there
+  is no `docker build`, `docker save` / `load` or `docker push`; Compose is a **read-only**
+  project view (grouping by project + project-level merged logs) and provides no `compose up` / `down` / `restart`.
+- **`volume prune` deletes data and its behaviour varies by version**: `docker volume prune` on docker ≥ 23
+  has `-a/--all`, and **without it only anonymous volumes go** (which is how this plugin calls it); but docker < 23
+  has no such switch, and a plain prune deletes **named** volumes that are not in use as well. The confirmation copy
+  for volume pruning therefore spells out the version difference; before running it, please confirm that there is no
+  data volume you want to keep.
+- **Network / volume mutations exist only as panel buttons, with no agent tools**: image remove / prune have
+  corresponding tools, but for this round networks / volumes only gained HTTP endpoints (`/networks/remove` and the
+  like) and panel buttons — deliberately without widening the mutation surface on the agent side. Letting the agent
+  delete them too would require adding separate tools (with their own confirmation conventions).
+- **The Overview only summarises "the container picture" and is entirely read-only**: the `Overview` next to the
+  target picker only does counter cards and the attention table pinned to the top, with **no cross-target operations
+  whatsoever** (start / stop / remove are still done one by one in a single target's list), and it does not merge
+  logs / stats / event streams either (those remain the business of single-target, single-container pages). In
+  addition, "attention" covers only `unhealthy` and
+  `restarting`: `ContainerSummary` has no `exitCode`, so a "crashed exit" cannot be told from a "manually
+  stopped" one, and counting every `exited` as an exception would let a container that was stopped once flood the
+  screen forever — look at dead containers under "stopped" in the counter card instead.
+- **The connection-bar button needs a matching target to have data**: the button always shows on an SSH tab, but if
+  the session host has no corresponding `kind=ssh` target (neither the connection-book name nor `host:port` matches),
+  clicking it only shows a hint that it is "not configured as a Docker target" instead of a container list; the
+  connection bar on local tabs is hidden entirely.
+  Target additions and removals are picked up within at most 30 seconds (saving the settings card refreshes
+  immediately).
+- **`enabled: false` needs a restart**: disabling the plugin does not unload the registered routes and tools (long
+  streams in progress — logs / stats / pulling — are wrapped up immediately, but the routes themselves remain), and
+  only restarting `dsh web` disables it completely.
+- **Mutating operations have no separate audit log**: only docker's own records and the host `ctx.logger`'s
+  ordinary output.
+
+- **The boundaries of cross-target aggregation**: concurrency cap 4, per-target timeout 45s; a single target failing
+  or timing out affects only its own cell (the group carries `error`). With many targets the Overview's request
+  volume grows linearly with the target count (2 requests per target), and auto refresh multiplies that volume —
+  with many targets it is best to turn auto refresh off.
+
+## How it works
+
+```
+Browser half (client.js)
+  ├─ sidebar "Containers" entry → panel: target picker / container list (search + state filter) /
+  │   container cards (action bar in two groups: view = terminal/logs/stats | mutate = start-stop/restart/remove) /
+  │   container list "Activity" strip (event-driven refresh) + "Select for merging" multi-select → temporary merged logs /
+  │   multi-target Overview (all targets fetched in parallel + progressive landing; counter cards / attention table pinned to the top; read-only) /
+  │   Compose project view (project grouping / service table / project-level merged logs) /
+  │   image list (inline details · remove) + image details (layers / build history) + pull progress /
+  │   network list + network details (subnet / connected containers) + volume list + volume details / one-shot exec
+  │     └─ terminal drawer: with tty ≥ 0.15, embeds tty's terminal in place via ttyTerminal.mount
+  │        (the panel does not collapse; collapsing/dragging only changes size and does not interrupt the session; only ✕ or closing the panel disposes,
+  │        and with an active session closing the panel confirms first → tty ends the session and tears down the DOM)
+  │     ├─ fetch → /api/dsh-docker/* (loopback fence)
+  │     ├─ FOLLOW → EventSource /logs/stream (SSE: 5000-line ring buffer / auto stick to bottom /
+  │     │   back to bottom / auto reconnect on disconnect / back to snapshot when the container exits)
+  │     ├─ stats FOLLOW → EventSource /stats/stream (SSE: a 60-point ring buffer draws
+  │     │   CPU / memory sparklines; **the frontend aborts it**, and the stream only ends when docker stats exits by itself)
+  │     ├─ events → EventSource /events/stream (SSE: the Activity strip's 50-entry ring buffer +
+  │     │   a 500ms debounce triggering a list refetch; one full refresh after a successful reconnect)
+  │     ├─ pull → EventSource /images/pull/stream (SSE: per-layer progress upserted by layer key)
+  │     └─ merged logs → one /logs/stream per container in the project, mixed client-side by [service]
+  ├─ optionally consumes tty's ttyConnbar service → SSH connection bar "Containers" button
+  │   (matches configured targets by book name / host:port; only appears on a hit)
+  ├─ optionally consumes tty's ttyPanel service (0.16.0) → docks to the right while the terminal panel is open
+  └─ optionally consumes tty's ttyTerminal service → the card's "Terminal" button opens a docker exec tab directly
+      (falls back to copying the command when tty is unavailable / credentials are not in the browser)
+
+Host half (src/index.ts)
+  ├─ settings namespace docker (~/.dsh/settings.yaml)
+  │   DOCKER_SETTINGS_SCHEMA → normalizeConfig (clamping / allowlisted keys)
+  ├─ read-only reuse of tty settings' sshHosts (connection book) and hostKeys (fingerprint seed)
+  ├─ resolveTarget: local → runLocal; ssh → look up the connection book via book or use inline fields
+  ├─ one DockerApi per target (src/docker.ts)
+  │   ├─ argv construction + assertRef allowlist + output cap (maxOutputKb)
+  │   └─ tolerant parsing: {{json .}} line by line / as an array, case-insensitive field names, degradation on missing fields
+  ├─ RemoteExec (src/ssh-exec.ts)
+  │   ├─ lazy connection pool: one connection reused per user@host:port, reclaimed after 120s idle
+  │   │   (swept every 30s, connect timeout 20s, keepalive 10s; long streams with busy>0 skip reclamation)
+  │   ├─ non-PTY exec channel: one channel per command, closed as soon as stdout/stderr are drained;
+  │   │   long streams (run()/stream()) have no overall timeout or output cap and are stopped via AbortSignal
+  │   ├─ shJoin single-quote escaping (parsed by the remote shell); env:VAR secret lookup
+  │   └─ hostVerifier TOFU pinning (record on first use, reject on change)
+  ├─ runLocal / runLocalStream: spawn(dockerBin, args) (no shell, local targets)
+  │   stop ladder: SIGTERM → SIGKILL if it has not exited in 2s
+  ├─ 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
+  │   ├─ /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}
+  │   ├─ /events/stream (read-only): docker events --filter type=container →
+  │   │   event{action,name,image,...} (allowlist filtered); the daemon side ending sends end{events-exit}
+  │   ├─ /images/pull/stream (allowMutations): docker pull → line{d|e} +
+  │   │   end{pull-exit,code,ref}; 403 and no stream when mutations are off
+  │   └─ plugin disabled / config hot-updated / uninstalled → all four streams get a uniform end + abort
+  ├─ 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_image_inspect / docker_networks / docker_volumes (always registered)
+     + docker_action / docker_image_remove / docker_image_prune / docker_image_pull
+       (allowMutations) / docker_exec (allowExec)
+```
+
+## Development and acceptance
+
+```bash
+pnpm --filter @hyzyn/dsh-docker build       # tsc → lib/ (host half) + esbuild → client.js (browser half)
+pnpm --filter @hyzyn/dsh-docker typecheck
+pnpm --filter @hyzyn/dsh-docker smoke       # three offline regression suites, none needing a docker daemon
+pnpm test                                    # repo-level vitest (including this package's logs-stream / streams suites)
+```
+
+`scripts/smoke.mjs` (33 items, reading the `lib/` build output) covers pure logic: ps parsing (field mapping /
+compose labels / ports / deriving a missing `State` / noise lines / JSON arrays), port-string parsing and
+deduplication, stats parsing (percentages / memory / IO / PIDs), abnormal input for size and percent, images parsing
+(dangling), **image inspect / history parsing (both the JSON and the plain-text-table path)**,
+inspect parsing (state / health / exit code / mounts / networks / ports / not throwing on missing fields),
+injection rejection for `assertRef` / **`assertImageRef` (admitting registry/digest, rejecting flags and
+injection)**, `assertBin`, `formatBytes`, `shJoin` escaping, `DockerApi`'s argv construction
+(ps / logs / action / exec / probe success and failure / **image inspect·rm·prune·pull·statsStream·pullStream**),
+`normalizeConfig` defaults and clamping, `sanitizeTargets` / `sanitizeHostKeys`,
+`resolveTarget`'s four paths, and `mergeTargetSecrets`' credential-preserving semantics.
+
+`scripts/route-smoke.mjs` (54 items) runs end to end with **a fake cordis ctx + a fake docker CLI script**: plugin
+mounting (settings / tools / routes / capability-announcement registration), the actual calls and returns of
+**26 routes** (including the event sequences and parameter validation of the four SSE streams `/logs/stream`,
+`/stats/stream`, `/events/stream`, `/images/pull/stream`, with the event stream additionally asserting that noise is
+dropped by the allowlist), the `docker_events` tool's snapshot output and its `since` character-set validation,
+`/images/inspect`'s details + build history, `/config` credential masking, 400 for unknown config keys, 403 for
+`/action`, `/exec` and image mutations (remove / prune / the pull stream) while read-only together with the
+corresponding tools not being registered, immediate unlocking after the switches are turned on (including the
+`settings/updated` hot-update path), 403 for non-loopback (including the three stream routes), container names /
+image references rejected by the allowlist when injection is attempted, the fallback when `target` is omitted and the
+error with several targets, and 403 on the stream routes after being disabled.
+
+`scripts/client-smoke.mjs` (27 items) executes the build artifact
+`client.js` in Node with minimal DOM / React stubs: verifying the registration id and factory shape, that it only
+requires modules provided by the platform seed
+(`react` / `react/jsx-runtime` / `react-dom/client`), that the settings card key registered by `apply` equals the
+namespace `docker`, that it degrades quietly when the host sidebar cannot be found and that unmount can be called
+repeatedly, the four paths of ttyConnbar integration (connection-book name hit / host:port hit / no button for an
+unconfigured host / silent skip when tty is not installed), FOLLOW's SSE subscription and the "back to bottom"
+interaction (static assertions), the **image details / pull stream / remove / prune entry points**,
+**stats FOLLOW + sparkline hooks**, **Compose grouping and merged logs**, **the "Activity" strip wiring + the event
+ring buffer / action labels / debounce** (pure logic through the `__events` test seam), and the style rule that hides
+the entry label when the sidebar is collapsed (`data-sidebar-collapsed`).
+Verification that needs a real daemon follows the manual checklist below.
+
+`test/logs-stream.test.ts` (27 cases, run by the root `pnpm test`) covers four layers of the live log stream:
+`logsStream`'s argv construction and `assertRef` allowlist, the single-line JSON encapsulation of SSE frames
+(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.
+
+`test/streams.test.ts` (33 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
+`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,
+`/images/pull/stream`'s allowMutations gate (403 and no stream) / `pull-exit` wrap-up / uniform wrap-up when
+disabled, **`assertName`'s validation matrix (`/` and `:` must be rejected — and those are exactly what
+`assertImageRef` admits), the ls·inspect·rm·prune argv for networks / volumes (prune must carry `-f`), tolerant
+ls·inspect parsing for network / volume (string booleans, older versions without `Mountpoint`, empty output / bad
+lines), and the gating of the eight `/networks` and `/volumes` endpoints (403 for remove/prune with the switches off,
+400 for a missing name, 500 for an illegal name)**, plus `formatBytes`.
+
+### Manual acceptance checklist
+
+1. **Local target**: add a `kind=local` target named `local`, and `probe` returns the server version;
+   the container list matches `docker ps -a` (including stopped containers).
+2. **SSH target**: with an entry already in the tty connection book, reference it via `book` → the container list /
+   details / logs work; the first connection logs "host key fingerprint recorded (TOFU)" and the second does not
+   prompt again; after manually changing the fingerprint in `hostKeys` and reconnecting, the connection should
+   **be rejected** with reset guidance.
+3. **Read-only interception**: with both switches off, `/action`, `/exec`, `/images/remove`,
+   `/images/prune`, `/images/pull/stream` all return 403; on the agent side there are only the 7 read-only tools, 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).
+4. **Logs / stats / images**: `tail` and `timestamps` / `since` take effect; stats show
+   CPU, memory, network and block IO; the image list carries a marker on dangling entries.
+5. **FOLLOW live log stream**: turning on `FOLLOW` on the log page → the status line first says
+   "connecting" and then "following live", and new lines from `docker logs -f` appear immediately (`docker run --rm alpine sh
+   -c 'i=0; while :; do echo line-$i; i=$((i+1)); sleep 1; done'` makes this observable);
+   with FOLLOW on, `AUTO REFRESH` is greyed out and polling stops; scrolling up brings up "back to bottom",
+   and clicking it returns to the bottom and resumes auto stick-to-bottom; turning FOLLOW off immediately returns to
+   snapshots. Stop the container → the stream receives
+   `end`, hints "the container has exited (exit code N)" and automatically does one more snapshot. Kill `dsh web` and
+   start it again (or hot-change the plugin config) → the status line briefly says "reconnecting" and then heals
+   itself, with no error banner. Run the same with an SSH target and confirm that panel operations such as
+   `docker ps` on the same host are unaffected while the stream runs (connection reuse), and that idle reclamation
+   (120s) does not cut the stream.
+6. **Stats live following**: turning on `FOLLOW` on the stats page → "connecting to the stats stream…" → "following
+   live (docker stats)", and the CPU / memory sparklines grow a little every second (run `docker run --rm
+   alpine sh -c 'while :; do :; done'` to watch CPU rise); turning FOLLOW off immediately returns to snapshots and
+   resumes polling. Stop the containers being measured → the stream receives `end` (stats-exit), hints, and then
+   returns to polling automatically.
+   Note that **this stream does not end naturally**: switching pages / closing the panel must close the `EventSource`
+   (on the host side `docker stats` should be seen being SIGTERM'd).
+7. **Image details / removal / pruning**: click "details" on a row of the images page → the layer count in the
+   overview matches `docker image inspect` and the build history matches `docker history` (Docker ≥ 26
+   goes through `--format`, older versions fall back to the plain-text table); look up a dangling row by image ID.
+   Click "remove" → after a second confirmation it runs `docker image rm`; removing an image that a container
+   references should fail with a hint.
+   "prune dangling" only removes untagged images, and its output ends with `Total reclaimed space`.
+8. **Pull progress stream**: the pull icon in the images toolbar (hovering shows "pull image") → enter a small image
+   you do not have locally (such as `alpine:3.20`)
+   → per-layer status lines appear live and are updated in place by layer; when it finishes it hints "pull complete"
+   and refreshes the list automatically.
+   Clicking "stop" mid-pull or leaving the view → `docker pull` is terminated by SIGTERM with no leftover process.
+   With "allow mutations" off the button is greyed out, and going straight to `/images/pull/stream` returns 403.
+9. **Compose project view**: start two or three services with a compose file (`docker compose up -d`) →
+   switch the toolbar to "Compose" → the services are grouped under one project card with the correct
+   running / service counts and states;
+   click into the project to see the service table, switch to "merged logs" → the services' logs appear mixed by the
+   `[service]` prefix (the equivalent of `docker compose logs -f`), and the filter box can filter by service name and
+   content; after turning "auto
+   scroll" off new logs keep entering the buffer without the view jumping. Containers without a compose label are
+   grouped under "other containers (non-compose)".
+10. **After turning on `allowMutations`**: stop / start / restart succeed; removing a running container
+    errors with a "stop it before removing" hint, and stopping first and then removing succeeds.
+11. **After turning on `allowExec`**: a command such as `ls -la /app` returns stdout and the exit code; changing the
+     command to `sleep 60` (with `timeoutSec` lowered) should be interrupted and report a timeout; a `command` longer
+     than 8000 characters is rejected.
+12. **The exec drawer coexists with the body** (tty ≥ 0.15): after opening the drawer from a card's "Terminal", switch
+    to logs / stats / another container's details, and both the drawer and the terminal session must stay alive;
+    **collapsing** (the arrow or double-clicking the top edge) squashes the drawer into one title bar and the session
+    keeps running (expanding restores it); **dragging the top edge** changes the height without exceeding 75% of the
+    panel; clicking the blank backdrop or the panel's ✕ should now raise an "end the container terminal session"
+    confirmation, and cancelling keeps the session alive while only confirming ends it (the tty side receives a kill).
+    Offline regression: `node packages/tty/scripts/preview.mjs docker-exec-logs`
+    (headless Chrome runs the real client: drawer + log page + collapse and expand, asserting that the session was
+    not ended).
+13. **Entering the container panel from the connection bar (dock mode, needs tty ≥ 0.16)**: open an SSH tab in the
+    tty panel →
+    connection bar "Containers" → the container panel should dock **to the right of the terminal** (not a full-screen
+    modal) while the terminal stays typable;
+    dragging the left edge resizes it (up to 72% of the panel width), the title-bar arrow collapses it into a narrow
+    strip (the terminal takes back the full width and the container panel is not unmounted), and ✕ tucks the panel
+    away without affecting the SSH tab; clicking a card's "Terminal" at this point should **open a new
+    `<container> · exec` tab in the same terminal panel** rather than nesting another terminal drawer.
+    Offline regression: `node packages/tty/scripts/preview.mjs docker-dock`
+    (asserting docked / no backdrop / the terminal widens after collapsing / the container panel survives).
+14. **Multi-select merged logs**: click `Select for merging` in the container list → checkboxes appear on the left of
+    the cards and the card action bars collapse;
+    check 2–3 containers → the action bar shows "3 containers selected", and clicking `merged logs` → the merged
+    view's title is
+    "merged logs · 3 containers" with the three streams mixed by the `[service]` / container-name prefix; with only 1
+    checked the button is greyed out and hints "select at least 2 containers", and at 9 checked it is greyed out and
+    hints at a maximum of 8; stop one of the containers from the list → that stream ends with the usual `end`
+    semantics while the others are unaffected.
+15. **Esc leaves selection mode**: pressing Esc in selection mode → back to the normal list, checks cleared and the
+    action bar gone;
+    clicking `Select for merging` again (its label is now `Exit selection`) has the same effect; switching targets /
+    switching segments / closing the panel also clear the selection mode and the checks together.
+16. **The Activity strip**: the "Activity" strip appears at the head of the container list, its status dot goes from
+    yellow to green and the copy reads "receiving live
+    (docker events)"; running `docker restart <container>` / `docker stop`+`start` → the
+    list state follows within 1 second and the Activity strip shows `stop` / `start` (abnormal exits show the coded
+    form such as `die(137)`); clicking the title collapses it (the event stream is not interrupted, and expanding
+    still shows the accumulated latest 8);
+    several consecutive `docker exec` calls **produce no events at all** (`exec_*` has already been dropped by the
+    server-side allowlist);
+    after the network drops / `dsh web` restarts, recovery briefly shows a yellow status dot and automatically does
+    one full list refresh.
+17. **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
+    `docker network
+    inspect`, an `internal` network carries a badge, and the "connected containers" tab lists container names and
+    IPv4.
+    The volume list's mountpoints match `docker volume ls` (over-long paths are truncated, hovering shows the full
+    value).
+    With "allow mutations" off, both prune icons and the remove key in details are grey; with it on:
+    removing a network that no container is attached to succeeds, while removing one still in use errors with a hint;
+    volume pruning raises a confirmation saying "the data will be deleted as well". **Note**: on docker < 23 volume
+    pruning also deletes named volumes, so it is best to confirm on a test target first.
+
+18. **Multi-target Overview**: configure two or more targets (local + one SSH) → the `Overview` pill appears next to
+    the target picker;
+    clicking it shows two counter cards on one screen (each badged "local" / "SSH") plus the attention area, with the
+    card numbers matching that target's
+    container list. Change one target's SSH address to something wrong (or stop the remote docker) and refresh →
+    only that card is outlined in red and "1 target unreachable" appears at the top, while the other card still shows
+    its results, and **the page does not**
+    wait for the SSH timeout before showing content (progressive landing). Click an attention row → it lands on that
+    container's details on that host, and going back gives
+    **that target's** container list rather than the Overview; click a counter card → that target's container list.
+    When everything is fine the attention area shows
+    "all good"; while targets are still answering it shows "reading…". Turning on "auto refresh" → polls all targets
+    at
+    `pollIntervalSec` (turning it off stops that).
+19. **Switching targets does not cross-talk (the list write gate)**: let Target1 (an unreachable SSH host) fail first
+    and raise an "operation failed" banner,
+    then immediately switch to the healthy Target2 → the banner should **disappear with the switch at once** and the
+    list should be Target2's containers; then wait 20s
+    so that Target1's timeout response comes back **after** that → the banner must not reappear and the list must not
+    be replaced with
+    Target1's containers. Entering from the Overview by clicking Target1's red counter card should likewise not show
+    the previous target's failure.
+    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.
+
+## Version / license
+
+`@hyzyn/dsh-docker` 0.3.1 · [Apache License 2.0](../../LICENSE)