@martintrojer/murmur 0.2.1 → 0.2.2

package/ARCHITECTURE.md

@@ -354,7 +354,7 @@ where the system interpreter is least yours to touch.
   "murmur_snapshot": 1,
   "host_id": "1d2ee96e-3a94-41b2-90fa-5f1ee2f04276",  // from identity.json
   "display_name": "mtrojer-mac",
-  "murmur_version": "0.2.1",         // read from package.json, never restated
+  "murmur_version": "0.2.2",         // read from package.json, never restated
   "generated_at": 1788105698997,     // this node's clock at build time
   "panes": [
     {
@@ -611,6 +611,83 @@ rendering a picker needs targets, and only ones it can reach. Identity is
 node's `host_id` and display name, which `peer add` records immediately rather
 than throwing away.
 
+Asymmetry is design with an unreported consequence: **if B does not peer A, B's
+picker cannot see A's agents, and no local surface can say so.** From A
+everything reads healthy, because from A it is.
+
+`murmur doctor` surveys each peer over ssh and reports it. Two calls per peer —
+`murmur export` for the `host_id`, `murmur peer list --json` for the roster —
+because a snapshot structurally cannot carry a roster (below) and `peer list`
+carries no `host_id`. Identity is compared on `host_id` only: names are local
+handles and `hostname` can be a container id, so comparing by name would report
+naming drift as asymmetry and miss genuine duplicates.
+
+Asymmetry is *reported*, never called a fault, and exits 0. Flagging the normal
+case — the laptop and the NAT'd server above — would train the operator to ignore
+the command. Only a duplicate `host_id` and a snapshot-version mismatch are
+problems, because both are murmur behaving provably wrongly. Skew is not
+recomputed: `doctor` calls the same `versionCell` `peer list` uses.
+
+"Island" is scoped to one hop and says so: *no peer that this node surveyed peers
+this host*, not "no node in the fleet". `doctor` asks its own peers and stops —
+multi-hop survey is a crawler, needing loop detection, a depth bound and a story
+for a node reachable from B but not from here, all to report on machines this
+node cannot fix anyway.
+
+`doctor --topology` adds the fact hub advice needs and murmur otherwise lacks:
+who can reach whom. One `ssh A "ssh B true"` per ordered pair — a bare `true`, so
+it measures transport alone, since "unreachable" and "reachable but murmur
+missing" have different fixes.
+
+Which node *can* hub is then a set intersection over the matrix, not a
+preference. A spoke counts only when reachability is proven in **both**
+directions, since the spoke collects from the hub and the hub from the spoke.
+When no node qualifies, nothing is recommended and the partition is reported.
+
+Measured while building it: on the author's fleet two peers reach nothing, no
+peer can resolve this node's own display name, and no whole-fleet hub exists. A
+recommendation would have been wrong.
+
+A failed probe is not a negative. It becomes `unreachable` only when the target
+is demonstrably up — it answered this node's survey seconds earlier — and
+otherwise it is `unknown`, because a firewall and a sleeping laptop are
+indistinguishable from one dial and hub advice built on the confusion would flip
+between runs as machines sleep. Nothing a survey learns is written to the store:
+it is a diagnostic that reaches out, not state murmur caches, and caching it
+would make `peer list` report facts no collect established.
+
+**The snapshot carries no peer roster, deliberately.** Publishing one would be
+the obvious way to make the fleet self-describing, and it is refused: a snapshot's
+contract is "my panes, complete and authoritative", which is exactly what makes
+"absent from a snapshot means absent" true. A roster is neither complete nor
+authoritative — it is one node's local configuration, and its truth lives on the
+node being described rather than the one describing. Putting membership into that
+document would also make every membership question a format question, needing a
+version bump and a coordinated fleet upgrade, which is a heavy price so soon
+after 0.2.1 given that `parseSnapshot` rejects a mismatched version outright.
+Surveying over ssh needs no format change and no fleet-wide upgrade, and it is
+honest about what it is: a question asked now, not a fact murmur stores.
+
+**Only `collect` could ever be relayed, which is why there is no broker.** Three
+surfaces need a path to a pane's host, and they are not alike:
+
+| surface | needs |
+|---|---|
+| collect | `ssh <target> murmur export` |
+| glance (the picker's preview) | `ssh <target> tmux capture-pane` |
+| jump | `ssh <target>`, interactively |
+
+Glance and jump are inherently point-to-point: a captured pane and an interactive
+session cannot be served by a third party holding neither. So a relay could only
+deduplicate `collect` — and `collect` is the cheap one, ~400 bytes per pane and
+~1.2KB per snapshot, measured.
+
+A broker would therefore dedupe the cheapest of the three, leave both interactive
+paths untouched, and add a daemon, a port and a second auth story to do it. That
+is why gossip and a NATS-style bus lost: they address payload, and payload was
+never the problem. The cost was one forked ssh per peer per repaint, fixed by
+throttling — see the collect floor in limitation 3.
+
 **Zero knobs.** Every exported setting is one the user can get wrong invisibly.
 Two are irreducible: `peers` (only the operator knows their fleet) and `theme`.
 Collection concurrency, deadlines and the staleness threshold are constants. The
@@ -639,83 +716,38 @@ deferral is the main reason murmur is small.
 
 ## Why not something else
 
-Investigated against herdr 0.8.2, a T3 Code checkout, and `mu`, all built and
-run locally rather than judged from their READMEs.
-
-| | multi-machine view | pi support | state source |
-| --- | --- | --- | --- |
-| herdr | no — 1:1, planned, blocked | yes | screen-scraped |
-| T3 Code | no — "unbuilt" by its own docs | no — 14-method adapter | driven |
-| mu | state sync yes, agents no | yes | reported |
-| **murmur** | **yes** | **yes, in-process** | **reported from inside** |
-
-### herdr
-
-A Rust terminal multiplexer built for coding agents: workspaces, tabs, panes, a
-per-pane `idle/working/blocked/done` sidebar, a socket API. Evaluated as a tmux
-replacement and rejected on its own terms.
-
-On multi-machine it is strictly 1:1. `--remote <target>` takes a single target,
-no subcommand has a `--host` flag, and `--remote` *replaces* the view rather
-than adding to it: two machines means two sessions and a full switch between
-them. Multi-client is the maintainer's stated top priority, gated behind a
-long-running server/client refactor.
-
-Waiting would not help. The scope is one client attaching to multiple *herdr*
-servers, so every machine must run herdr — including machines where you cannot
-choose the multiplexer. And herdr detects state by matching terminal output, so
-adopting it trades reporting from inside the agent for screen-scraping.
-
-Taken from it: integration installs that write hooks into each agent's own
-config directory (`murmur link pi`), reusing one authenticated connection, and
-its own stated non-goals: no merged PTYs across machines, no moving work between
-hosts, host as a lightweight label. Rejected: the always-present sidebar, not
-for its ~4 columns but because it is fixed to one edge and cannot become a
-horizontal strip, while a status row is overhead already paid.
-
-### T3 Code
-
-An "agent harness control surface": a server owning agent sessions plus web,
-desktop and mobile clients over one RPC WebSocket.
-
-Its remote access is well ahead of herdr: direct ws/wss, bearer pairing, relay
-tunnels, mesh-VPN serve and desktop-managed SSH, all shipped. But the aggregated
-view is unbuilt by its own internals docs — multiple live connections exist, a
-fused cross-machine overview does not.
-
-It also does not support pi, and adding it is expensive: a provider needs a
-driver plus a fourteen-method adapter, and the reference implementation is over
-1700 lines. murmur's adapter problem is smaller structurally: T3 Code drives an
-agent it does not live inside, while murmur's extension runs *in process* and
-calls the store directly.
-
-Taken from it: the rule that *remoteness is expressed at the connection layer,
-never by splitting the runtime* (murmur's channel seam is exactly this),
-transport is not an identity, and environment identity as a stable UUID rather
-than a hostname.
-
-### mu
-
-An agent orchestrator: workstreams, a task DAG, agents in panes, isolated
-workspaces. It solved machine identity and cross-machine sync for its own
-problem, which is a genuinely harder one: mu replicates *writes* from many
-nodes, so it needs an op-log and per-peer watermarks.
-
-Two ideas taken directly. Sync is ambient rather than a daemon: every invocation
-syncs before the verb, and no watcher outlives the command. And sync never fails
-a command — every ambient entry point is total, and a dead peer warns and
-returns.
-
-One idea deliberately not taken: mu's generic replicated KV. A generic op-log
-needs conflict resolution, which single-writer-per-node caching skips entirely,
-and a murmur with `put`/`del` over arbitrary entities would just *be* mu. The
-same reasoning is why murmur ships no log of its own — nothing here is authored
-by two parties, so there is nothing to merge.
-
-**Relationship:** murmur observes, mu orchestrates. Merging is plausible later,
-since murmur would give mu global agent addressing and remote observation. But
-remote *orchestration* is much harder than remote observation, and none of it is
-murmur's problem.
+Version numbers and roadmap status are deliberately absent here: they were true
+on the day they were checked and are the first thing to rot. What follows is the
+structural difference, which does not move.
+
+**Terminal multiplexers built for agents** (herdr and similar) own the panes and
+infer state by matching terminal output. Two consequences: every machine must run
+that multiplexer, which is not a choice you always have, and state is scraped
+rather than reported. murmur takes tmux as given and has the agent report from
+inside its own process.
+
+**Harness control surfaces** (T3 Code and similar) run a server that owns agent
+sessions, with clients over RPC. Their remote *access* is strong. The structural
+cost is the adapter: driving an agent you do not live inside needs a per-harness
+driver, where murmur's extension runs in-process and calls the store directly.
+
+**Orchestrators** (`mu`) place work and replicate writes from many nodes, so they
+need an op-log, watermarks and conflict resolution. murmur observes and never
+places work, so single-writer-per-node caching removes all of it. **murmur
+observes, mu orchestrates.** Merging is plausible — murmur would give mu global
+agent addressing — but remote orchestration is a much harder problem than remote
+observation, and it is not murmur's.
+
+Taken from these tools, and worth stating because each is load-bearing above:
+integration installs that write hooks into each agent's own config (`murmur link
+pi`); reusing one authenticated connection; remoteness expressed at the
+connection layer rather than by splitting the runtime; identity as a stable UUID
+rather than a hostname; and ambient sync with no daemon, where every invocation
+syncs before the verb and no watcher outlives the command.
+
+Deliberately not taken: a generic replicated KV. A generic op-log needs conflict
+resolution, which single-writer caching skips entirely, and a murmur with
+`put`/`del` over arbitrary entities would just *be* mu.
 
 ## The extension's lifecycle assumptions
 
@@ -871,9 +903,25 @@ each was cheaper to accept than to solve:
    only peer names and targets salvaged. A node serving the old event format is
    reported as reachable-but-broken, which is the honest description: the two
    cannot federate.
-3. **No incremental sync.** Every collect transfers each peer's whole snapshot.
-   It is bounded by live pane count, so it is small — but it is O(panes) per
-   tick rather than O(changes).
+3. **No incremental sync.** Every collect transfers each peer's whole snapshot,
+   so it is O(panes) rather than O(changes) — bounded by live pane count, and
+   small in absolute terms: ~400 bytes per pane and ~1.2KB for a whole snapshot,
+   measured. It is no longer *per tick*, though, and that was the part that
+   mattered. Fetch rate used to be tied to redraw rate, because `murmur status`
+   collects and tmux re-runs it every `status-interval`; the cost is quadratic in
+   a mesh and multiplied again per attached client, since the interval fires per
+   client. An ambient collect now skips a peer attempted within
+   `COLLECT_FLOOR_MS` ± `COLLECT_JITTER_MS / 2` (30s ± 10s), measured at 1.08s →
+   0.05s for `murmur status` against four real peers. Keyed on
+   `last_attempt_at`, not `fetched_at`: the expensive peer is the one that does
+   *not* answer, since it holds a forked ssh until `ConnectTimeout`, and keying
+   on success would exempt exactly the sleeping laptops the floor exists to stop
+   hammering. The jitter is drawn per peer per call and is what stops the floor
+   becoming a synchroniser — a bare floor makes a fleet converge on hitting one
+   machine in the same instant, permanently. Only ambient callers pass a floor:
+   `murmur collect` is a person asking, and the picker is a keypress, including
+   its `^r` refresh, where a floor would be a refresh key that silently does
+   nothing.
 4. **No nested agents.** A second live process in one pane is refused and
    reports nothing. A pane shows at most one agent.
 5. **No remote liveness inference.** `owner_pid` never crosses the wire, so a

package/CHANGELOG.md

@@ -3,6 +3,104 @@
 Notable changes per release. Written for someone deciding whether to upgrade,
 so it says what changed for a user rather than listing every commit.
 
+## 0.2.2
+
+**The picker's name column shows `murmur`, not `hacking/murmur`.** 0.2.1 fixed
+*which* source a name comes from; this fixes how the session name is rendered
+once it gets there. Session names are conventionally paths — that is how `tms`
+and similar tools name them — and the last segment is the part that identifies
+the work, so that is what the name column shows now.
+
+That fallback is hit more often than it looks: an agent has no name from a richer
+source unless mu set one or you ran pi's `/name`, because pi's own auto-namer runs
+when a session closes. So a live hand-started pi — exactly the agent you are
+looking at — fell through to the session name. The full path is not lost; it is
+still in the stream column beside the name, so the row is strictly more
+informative than before at the same width. Names you or mu chose are never
+shortened.
+
+**`murmur status` no longer reaches your peers on every status-bar repaint.**
+Collection was driven by the tmux status bar — `status` collects, and tmux re-runs
+it every `status-interval` — so fetch rate was tied to redraw rate. On a
+four-peer node `murmur status` took 1.08s; it now takes 0.05s. If your status bar
+felt sluggish, or you saw a lot of ssh processes on a machine doing nothing in
+particular, that is this.
+
+An ambient collect now skips a peer attempted in the last 30s (±10s of jitter, so
+a fleet does not converge on hitting one machine at the same instant). Commands
+you run yourself are unaffected: `murmur collect` fetches every peer, and so does
+the picker, including its `^r` refresh. The visible trade is that a peer's data
+can be up to ~40s old in the status bar rather than one tick old; the staleness
+threshold is well above that, so a reachable peer still reads as fresh.
+
+**New: `murmur doctor` reports what only a fleet-wide view can see.** Membership
+is per node, so peering a machine does not mean it peers you — and if it does
+not, its picker cannot see your agents. No local surface could tell you that,
+because from your node everything reads healthy. `doctor` surveys each peer over
+ssh and names it, along with duplicate hosts configured twice, snapshot-version
+skew, one machine known under different names, and peers it could not survey at
+all.
+
+```
+$ murmur doctor
+Surveyed 4 peers, 4 answered.
+5 observations, nothing broken.
+
+One-way peering
+  These do not peer this node, so their pickers cannot see its agents.
+  bubba     does not peer mtrojer-mac
+  gardenpc  does not peer mtrojer-mac
+
+Do this
+  ssh bubba murmur peer add mtrojer-mac
+  ssh gardenpc murmur peer add mtrojer-mac
+```
+
+It is read-only — nothing is written to the store and there is no `--fix`, since
+every repair runs on another machine. Repairs are printed for you to run. Exit
+status is 0 for observations and 1 only for a real problem, so it is safe in a
+script, and asymmetry is an observation: reachability is *meant* to be
+one-directional in places, and a check that failed on the normal case would be a
+check you learn to ignore. `--json` gives the finding list with machine-readable
+severity.
+
+Worth knowing before you act on its advice: the suggested commands name your node
+by the name it calls itself, and that name may not resolve from the peer's side.
+On the author's fleet none of them could resolve it, so each suggestion needed an
+address the far host can reach.
+
+**New: `murmur doctor --topology` computes which fleet shapes are actually
+possible.** Opt-in, because it costs one ssh dial per ordered pair (4 peers is
+20) where the survey costs one per peer.
+
+```
+$ murmur doctor --topology
+Reachability  20 ordered pairs probed across 5 nodes
+               REACHES                 CANNOT REACH
+  mtrojer-mac  all 4                   -
+  bubba        -                       mtrojer-mac gardenpc linuxpc macmini
+  linuxpc      gardenpc macmini        mtrojer-mac bubba
+  macmini      bubba gardenpc linuxpc  mtrojer-mac
+
+Hub  linuxpc  serves {linuxpc, macmini}, leaves out mtrojer-mac, bubba, gardenpc
+```
+
+When no node can hub the fleet it recommends nothing and reports the partition,
+which is the useful half — a hub half the fleet cannot reach is worse than no
+hub. When one exists it prints the commands to build it, and states what a star
+costs: spokes see the hub and the hub sees everyone, but spokes do not see each
+other. A pair whose target was not demonstrably up is `unknown` rather than
+unreachable, so a sleeping laptop is never reported as a firewall.
+
+**The doctor report is tables, not prose.** Findings are grouped by kind with the
+shared consequence stated once per group instead of once per row, and every
+suggested command is collected under one deduplicated `Do this` block rather than
+scattered through the text. The widest line went 129 columns to 78.
+
+No upgrade coordination needed for any of this: the snapshot format is unchanged,
+and `doctor` works against peers running 0.2.1. A peer too old for `peer list
+--json` is reported as needing an upgrade rather than as broken.
+
 ## 0.2.1
 
 **Agents are named by their tmux session, not by whatever process tmux found

package/README.md

@@ -2,12 +2,11 @@
 
 **Every coding agent you have running, on every machine, in one list.**
 
-You have agents on your laptop, your desktop, and a box somewhere else. One of
-them is blocked waiting on you right now. Which one?
+You have agents on your laptop, your desktop, and a box somewhere else. One is
+blocked waiting on you. Which one?
 
-Today you find out by walking the machines. Attach here, glance there, try to
-remember where you left that session. murmur answers the question in one
-keystroke, then jumps you to the agent on whichever machine it turns out to be.
+Without murmur you walk the machines to find out. murmur answers in one
+keystroke and jumps you to the agent, wherever it is running.
 
 ```
      state    agent                          workstream    host           age / flags
@@ -17,53 +16,33 @@ keystroke, then jumps you to the agent on whichever machine it turns out to be.
    · idle     worker-2                        infra           here          crew
 ```
 
-Pick a row and press enter. Local agents are a window switch away; remote ones
-open over ssh. The preview beside the list shows the last few lines the agent
-printed, so you can tell "waiting on me" from "still thinking" without going
-there at all.
-
-## Why it exists
-
-The tools in this space are excellent at one machine and stop there.
-[herdr](https://herdr.dev) is strictly one client to one server, and its
-multi-client work is blocked behind an unfinished refactor. T3 Code has better
-remote *access* than anything else here, but lists the aggregated view as
-unbuilt in its own docs. Both infer agent state by matching terminal output.
-
-murmur takes a different bet. The agent reports its own state from inside the
-process, and the machines exchange nothing more complicated than "here is
-everything I currently know". Knowing what is happening is the hard part, and reporting
-it from inside the agent is what makes it reliable.
+Pick a row, press enter. Local agents are a window switch; remote ones open over
+ssh. The preview shows the last lines the agent printed, so you can tell "waiting
+on me" from "still thinking" without going there.
 
 ## What it is
 
-- **A state layer over tmux:** tmux keeps owning your panes. murmur owns the
-  answer to "what is every agent doing right now".
-- **Reported state, not scraped:** a pi extension reports from inside the agent.
-  Nothing screen-scrapes, and a crash is detected from a pid rather than guessed
-  from output.
-- **Current state only:** each node publishes one complete snapshot of what its
-  panes are doing right now. No history, no log, nothing to replay — which is
-  why a peer's whole answer can be replaced in one write and absence means
-  absence.
-- **No daemon, no listening socket, no master:** peers are pulled over ssh when
-  you run a command. Every node can aggregate; none is special.
-- **Fast with one machine:** it replaced a local-only script and got quicker
-  doing it, ~50 ms to first paint against 250 ms. Configuring zero peers is the
-  common case, and nothing about it is degraded.
+- **A state layer over tmux.** tmux owns your panes; murmur owns the answer to
+  "what is every agent doing right now".
+- **Reported state, not scraped.** A pi extension reports from inside the agent,
+  so a crash is detected from a pid rather than guessed from output.
+- **Current state only.** Each node publishes one complete snapshot. No history
+  and nothing to replay, which is why a peer's answer is replaced in one write
+  and absence means absence.
+- **No daemon, no socket, no master.** Peers are pulled over ssh when you run a
+  command. Every node aggregates; none is special.
+- **Fast with one machine.** ~50 ms to first paint. Zero peers is the common
+  case and nothing about it is degraded.
 
 ## What it is not
 
-It does not orchestrate. It observes and connects, and never places work; that
-is [`mu`](https://github.com/martintrojer/mu)'s job.
-
-It is not a remote terminal. You can glance at a remote pane or jump to it, but
-there is no frame streaming and no resize negotiation, which is most of why it
-stays small.
-
-It does not replace your multiplexer. See
-[ARCHITECTURE.md](ARCHITECTURE.md#why-not-something-else) for the comparison
-against herdr, T3 Code and `mu`.
+- **Not an orchestrator.** It observes and connects, never places work. That is
+  [`mu`](https://github.com/martintrojer/mu)'s job.
+- **Not a remote terminal.** Glance at a pane or jump to it; there is no frame
+  streaming or resize negotiation. That deferral is most of why murmur is small.
+- **Not a multiplexer.** tmux stays. See
+  [ARCHITECTURE.md](ARCHITECTURE.md#why-not-something-else) for how murmur
+  relates to adjacent tools.
 
 ## Requirements
 
@@ -180,8 +159,68 @@ picker to a key:
 murmur peer list         # your peers, and when each was last seen
 murmur peer list --all   # also ssh hosts that could become peers
 murmur peer add devbox   # an ssh target; identity is discovered
+murmur doctor            # survey each peer over ssh: what only a fleet view shows
+murmur doctor --topology # also probe who can reach whom, and compute hub options
+```
+
+`peer list` reads local state: what you configured, and when you last heard from
+it. `doctor` dials out and asks each peer about *itself* — the only way to see
+what no local surface can: **membership is per node, so peering a machine does
+not mean it peers you.** If it does not, its picker cannot see your agents.
+
+`doctor` writes nothing and repairs nothing; it prints the commands. Exit 0 for
+observations, 1 only for a real problem, so it is safe in a script.
+
+```
+$ murmur doctor
+Surveyed 4 peers, 4 answered.
+5 observations, nothing broken.
+
+Not visible to the fleet
+  mtrojer-mac  none of the 4 surveyed peers can see this node
+
+One-way peering
+  These do not peer this node, so their pickers cannot see its agents.
+  bubba     does not peer mtrojer-mac
+  gardenpc  does not peer mtrojer-mac
+
+Do this
+  ssh bubba murmur peer add mtrojer-mac
+  ssh gardenpc murmur peer add mtrojer-mac
+```
+
+Suggestions name this node as it calls itself, and that name may not resolve from
+the peer's side — hence "check", not "run for you". `peer add` accepts a target
+that does not answer yet and discovers identity on the first collect, so trying
+costs nothing.
+
+`--topology` is opt-in: it costs one dial per ordered pair (4 peers is 20) where
+the survey costs one per peer. Plain `doctor` answers "is my fleet mutual?";
+`--topology` answers "what shapes are possible here?", which you ask once while
+setting up.
+
+```
+$ murmur doctor --topology
+Reachability  20 ordered pairs probed across 5 nodes
+               REACHES                 CANNOT REACH
+  mtrojer-mac  all 4                   -
+  bubba        -                       mtrojer-mac gardenpc linuxpc macmini
+  linuxpc      gardenpc macmini        mtrojer-mac bubba
+  macmini      bubba gardenpc linuxpc  mtrojer-mac
+
+Hub  linuxpc  serves {linuxpc, macmini}, leaves out mtrojer-mac, bubba, gardenpc
 ```
 
+Which node *can* hub is arithmetic on that matrix, not a preference. When none
+qualifies, nothing is recommended and the partition is reported — a hub half the
+fleet cannot reach is worse than no hub. A pair whose target was not
+demonstrably up reads `unknown`, not unreachable: a sleeping laptop and a
+firewall need different fixes.
+
+A star also costs something the output states every time it names one: spokes see
+the hub and the hub sees every spoke, but **spokes do not see each other**, since
+`export` publishes local panes only.
+
 Nodes being asleep or switched off is the normal state of a fleet, so nothing
 warns about it on a polling path: `murmur status` and `murmur pick` stay silent
 whatever the peers are doing. `murmur peer list` has a LAST SEEN column, and
@@ -192,35 +231,31 @@ could not reach.
 bind -N "agent state picker" a display-popup -E -w 80% -h 60% "murmur pick"
 ```
 
-In the picker: `^r` refreshes, `^p` cycles the preview, and `^u` clears the
-filter. `M-b` / `M-w` / `M-d` / `M-x` filter to blocked,
-running, done or crashed, and `M-a` toggles orchestrated agents in and out of
-the list. Alt rather than ctrl because `^b` is tmux's own prefix, which a popup
-never receives. Typing matches the agent name, its workstream or tmux
-session, and its host, as literal substrings rather than scattered characters.
+In the picker: `^r` refreshes, `^p` cycles the preview, `^u` clears the filter.
+`M-b` / `M-w` / `M-d` / `M-x` filter to blocked, running, done or crashed; `M-a`
+toggles orchestrated agents. Alt rather than ctrl because `^b` is tmux's prefix,
+which a popup never receives. Typing matches agent name, workstream or tmux
+session, and host, as literal substrings.
 
 `murmur status` prints per-state counts for a status bar. Everything else is
 `--help`.
 
 ## Jumping to a remote agent
 
-A remote jump opens the `ssh -t <host> tmux attach` in a local tmux session of
-its own, named after the peer with a trailing `~`. That session sets two options
-on itself, and both are why the jump does not feel like nested tmux:
+A remote jump runs `ssh -t <host> tmux attach` in its own local tmux session,
+named after the peer with a trailing `~`. That session sets two options on
+itself, which is why it does not feel like nested tmux:
 
-- `status off` — no local status bar, so the remote's own bar is the only one on
-  screen and the jump reads as a full-screen ssh.
-- `prefix None` — no local prefix at all, so `^b` goes straight to the remote.
-  No `^b b`, and no second prefix to learn.
+- `status off` — the remote's bar is the only one on screen.
+- `prefix None` — `^b` goes straight to the remote. No `^b b` to learn.
 
-Both are per-session, so your other sessions keep their prefix and status bar.
-When you leave the remote — inner `^b d`, the remote session ending, or the ssh
-dropping — the wrapper returns you to the exact window you jumped from and
-disappears. Jumping to the same host twice reuses the one session.
+Both are per-session, so your other sessions are unaffected. Leaving the remote
+(inner `^b d`, the session ending, or the ssh dropping) returns you to the window
+you jumped from and destroys the wrapper. Jumping to the same host twice reuses
+one session.
 
-The tradeoff: while you are inside the wrapper, the local tmux has no prefix, so
-you cannot reach it. If you want an escape hatch that does not involve the
-remote, bind one key in the root table:
+The tradeoff: inside the wrapper the local tmux has no prefix, so you cannot
+reach it. For an escape hatch, bind one key in the root table:
 
 ```tmux
 # Alt-Escape detaches out of a murmur wrapper session, and does nothing
@@ -235,7 +270,7 @@ already full-screen, and you land back at your shell prompt on exit.
 
 ## Status
 
-**0.2.1.** In daily use on one machine and verified across two over real ssh.
+**0.2.2.** In daily use on one machine and verified across two over real ssh.
 It is new and not battle-tested. The known gaps and the accepted limitations are
 listed at the end of [ARCHITECTURE.md](ARCHITECTURE.md#known-gaps).
 
@@ -246,9 +281,9 @@ shows each peer's version for exactly this. Upgrade the fleet together.
 
 ## Documentation
 
-[ARCHITECTURE.md](ARCHITECTURE.md) explains how it works: the three independent
-facts the whole model rests on, why it exists rather than the alternatives, what
-it deliberately cannot do, and what is unfinished.
+[ARCHITECTURE.md](ARCHITECTURE.md): the three independent facts the model rests
+on, the design choices and what they cost, what murmur deliberately cannot do,
+and what is unfinished.
 
 ---