@martintrojer/murmur 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,103 @@
 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.0
+
+**murmur now stores current state instead of an event log, and every node
+publishes one complete snapshot of it.** This is a rewrite of the model, and it
+is not compatible with 0.1.4 or anything before it. Upgrade every node together.
+
+The old design appended events and folded them into a state per agent at read
+time. It was the right shape for a tool that needed history, and murmur never
+did: nothing replays events, the picker's preview is a live `capture-pane`, and
+the only question anyone asks is "what is happening right now". The fold paid
+for that flexibility in bugs, and they were not small ones.
+
+What replaces it is three independent facts, each with exactly one writer:
+
+- **activity** -- is a process working in this pane. Written only by that
+  process.
+- **attention** -- does someone need to look at this pane: `done`, `blocked` or
+  `crashed`. Written by the owner, by an external notifier, or by local
+  reconciliation, and addressed by pane rather than by agent.
+- **freshness** -- how recently we reached the node that reported. Known only by
+  the reader.
+
+They are never collapsed into one value, and that is the fix for the worst bug
+this project has had. `murmur notify` followed by a tmux focus hook used to
+replace a running agent's state with `blocked` and then null its name, workstream
+and driver -- on three live panes, with all three processes running. It happened
+because everything was one enum in one table, so an attention writer could
+overwrite an agent's state simply by writing the row it was allowed to write.
+Attention now lives in its own table with no column an agent field could go in.
+It is not that murmur checks; it is that there is nothing to check.
+
+**A second agent in one pane is refused by the database, not by an environment
+variable.** A pane holds at most one instrumented agent, enforced by a `UNIQUE`
+constraint plus one liveness probe. A nested pi -- a subagent, or `pi` typed by
+hand inside an agent's pane -- registers no handlers, writes nothing and paints
+no badge. The previous mechanism passed a marker through the environment, which a
+process launched in an unusual way could drop.
+
+**Focus can no longer damage an agent.** `murmur clear` is one delete against the
+attention table. The whitelist of clearable states, the "is this agent still
+working" lookup and the metadata copy-forward are all gone, along with the
+possibility of getting any of them wrong.
+
+**A peer's whole state is replaced in one write, or not at all.** `murmur export`
+takes no options and prints one JSON document describing every pane on that node.
+A collect is one ssh round trip per peer, and the answer either replaces that
+peer's cache entirely or leaves it untouched. Watermarks, epochs, `--since`, the
+refetch-from-zero path and the wipe-detection machinery are all deleted -- none
+of them are needed once a document is complete, because absence from it means
+absence. A wiped node is no longer invisible to its peers for the same reason,
+with nothing added to detect the wipe.
+
+**A snapshot that does not validate is rejected before it is stored**, and the
+peer is reported as reachable-but-broken with the reason on it, rather than
+silently stale. That includes a version mismatch: fields are no longer carried
+through unrecognised, because a reader that guesses about state a human acts on
+is worse than one that says it cannot read the answer. `murmur peer list` shows
+each peer's version so a bad pairing is visible before you debug it.
+
+**A jump that fails changes nothing.** Pressing enter on a pane that has gone
+away reports it and leaves every row alone. Only the node that owns a pane
+retires it, on its next reconciliation. The picker's delete key is gone with the
+per-agent replica rows it evicted, and its history preview is gone with the
+history.
+
+Breaking changes, in the order you will hit them:
+
+- **`state.db` replaces `events.db`.** The old file is not migrated and is
+  deleted on first open. Peer names and targets survive; nothing else does.
+- **`murmur export --since N` is gone.** The command takes no options.
+- **`murmur status --json` has a new shape:** `{counts, orchestrated_counts,
+  panes, peers}`, where `counts` is keyed by the word a surface paints
+  (`crashed`, `blocked`, `done`, `running`, `idle`) and `panes` is a list of
+  panes rather than agents. `murmur status` without `--json` is unchanged.
+- **Old and new nodes cannot federate.** An older peer serves the event format,
+  which this version rejects as an invalid document. It shows up as broken, with
+  a message saying so.
+- **The SDK surface changed with the model.** The store's log methods, the fold
+  module and the wire envelope types are gone; `Store`, `Snapshot`, `PaneView`
+  and the pure `parseSnapshot` / `paneViews` / `renderState` replace them.
+
+What this costs, stated so it is design rather than surprise: there is no history
+of any kind, no incremental sync (each collect transfers a whole snapshot, which
+is bounded by live pane count), no nested agents, and no inference about whether
+a remote process is alive -- a remote pane's activity is whatever its own node
+last said, and a stale node keeps its last-known values beside a warning.
+ARCHITECTURE.md lists all eight accepted limitations.
+
+Tests went 134 to 239 across 28 files, and they changed character with the model:
+the ones that matter now assert what is *impossible* -- a notifier cannot touch
+an agent row, a focus hook cannot change activity, no read path carries a pid --
+several of them structurally, over the whole returned object graph rather than by
+reading a type. Every new test was verified by breaking the code it covers. Test
+processes are also now guaranteed not to touch the developer's own state, which
+is not hypothetical: writing the contract for this rewrite corrupted the author's
+live state three separate times, through the very bug being fixed.
+
 ## 0.1.4
 
 A review pass over the peer-collection code, and the bugs it found.

package/README.md

@@ -12,7 +12,7 @@ keystroke, then jumps you to the agent on whichever machine it turns out to be.
 ```
      state    agent                          workstream    host           age / flags
    ! blocked  review the auth change          api           → devbox        4m
-   ▶ working  Fix the picker filter           murmur          here
+   ▶ running  Fix the picker filter           murmur          here
    ✓ done     migrate the fixtures            api           → devbox        12m
    · idle     worker-2                        infra           here          crew
 ```
@@ -31,21 +31,25 @@ 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 my
-log since event N". Knowing what is happening is the hard part, and reporting
+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.
 
 ## 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".
-- **Push-based state:** a pi extension reports from inside the agent. Nothing
-  screen-scrapes, and a crash is detected from a pid rather than guessed from
-  output.
+- **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, 48 ms to first paint against 250 ms. Configuring zero peers is the
+  doing it, ~50 ms to first paint against 250 ms. Configuring zero peers is the
   common case, and nothing about it is degraded.
 
 ## What it is not
@@ -82,8 +86,19 @@ murmur init      # this node's identity
 murmur link pi   # install the agent-side extension
 ```
 
-`link pi` writes the extension into `~/.pi/agent/extensions/`, pinned to this
-installation. Re-run it after upgrading murmur.
+`link pi` writes a one-line extension into `~/.pi/agent/extensions/` that
+re-exports this installation, so `npm install -g` is the whole upgrade and
+there is nothing to re-run. Running agents keep the old code until they
+restart, which is true of any extension change.
+
+Re-run `link pi` only if the install path itself moves. `link pi --copy`
+inlines the extension instead, which pins it to the version that wrote it and
+does need re-linking after every upgrade — use it only if the extension has to
+keep working when the murmur install is gone.
+
+Order matters: without `murmur init` the extension loads and records nothing,
+because a node with no identity has nothing to publish state as. `link pi` says
+so if you skip it.
 
 Also on every node, in `.tmux.conf`, so a finished agent stops asking for
 attention once you look at it:
@@ -94,52 +109,146 @@ set-hook -g after-select-window    "run-shell -b 'murmur clear --pane #{pane_id}
 set-hook -g client-session-changed "run-shell -b 'murmur clear --pane #{pane_id}'"
 ```
 
-These are per node and not optional. The `cleared` event they write replicates,
-so a node without them leaves its agents marked `done` in *every* peer's picker,
-not only its own status bar. Verify with `tmux show-hooks -g`: `set-hook`
-accepts a hook name your tmux does not have and exits 0, so a wrong name fails
-silently.
+These are per node and not optional. `murmur clear` is the only thing that
+acknowledges an attention request, and a node's own snapshot is what every peer
+reads — so a node without these hooks leaves its finished agents marked `done` in
+*every* peer's picker, not only its own status bar. Verify with `tmux show-hooks
+-g`: `set-hook` accepts a hook name your tmux does not have and exits 0, so a
+wrong name fails silently.
+
+Focus can only ever cancel a request for attention. It cannot stop a running
+agent or alter anything the agent reported about itself, so there is no way to
+wire these hooks such that looking at a pane damages the agent in it.
 
 The pane id is passed explicitly because hooks run in the tmux server, where
 `$TMUX_PANE` is unset, and because the badge belongs to the window while "you
 looked at it" is true of one pane. Without it, a window holding an agent and a
 shell clears when you focus the shell.
 
+### Harnesses other than pi
+
+pi reports from inside itself, through the extension. codex and opencode have no
+such hook -- they can only run a command when something happens -- so they use
+`murmur notify`, which records an attention request for the pane it runs in:
+
+```toml
+# ~/.codex/config.toml
+notify = ["/bin/sh", "-lc", "murmur notify --source codex --event-type notify --title Codex"]
+```
+
+The same four fields may arrive as a JSON object on stdin instead, which is
+opencode's plugin form; flags win over the payload, so the line above behaves
+identically either way.
+
+**A hook is not an interactive shell, so check that `murmur` resolves in it.**
+A notify hook inherits the PATH of whatever launched the harness, and `sh -l`
+does not fix that -- `/bin/sh` is not your login shell and does not read your
+zsh profile. A harness started from a terminal inherits a PATH with your npm
+prefix on it and works; one started by a launcher, a daemon or a GUI may not,
+and the failure is silent because a notify hook's output goes nowhere. Verify
+from inside the harness, not from your terminal:
+
+```bash
+murmur notify --source probe --message reachable && murmur status
+# then undo it, or the pane stays badged:
+murmur clear --pane "$TMUX_PANE"
+```
+
+The probe is a real attention request: it records `blocked` and badges the
+window, which is what makes it a genuine test of the path. `murmur clear` is
+what takes it back, and focusing the pane does the same if you have the hooks
+above installed.
+
+If `murmur` is not reachable there, give the hook the absolute path
+(`command -v murmur` from your shell) rather than relying on PATH.
+
+`notify` is the one path where a process that does not own a pane may write
+about it, and it is narrow by construction rather than by convention: an
+attention request has no field for an agent id, a pid, an activity or any owner
+metadata, so it cannot make a claim about a process even by mistake. It says
+`blocked` and nothing else; running, done and crashed stay the pane owner's and
+murmur's own reconciliation's. Outside tmux it records nothing and exits 0, so it
+cannot break the caller's own exit code.
+
+A pane reached only this way — a codex agent murmur never instrumented — is a
+full row in the list: it shows up, it is filterable, and enter jumps to it.
+
 Then, on whichever machine you want to watch from, add the peers and bind the
 picker to a key:
 
 ```bash
+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
 ```
 
+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
+`murmur collect` -- which you run deliberately -- prints one line per peer it
+could not reach.
+
 ```tmux
 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 `del` drops a stuck
-row. `^b` / `^w` / `^d` / `^x` filter to blocked, working, done or crashed, and
-`^a` clears the filter. Typing matches the agent name, its workstream or tmux
+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.
 
 `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:
+
+- `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.
+
+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.
+
+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:
+
+```tmux
+# Alt-Escape detaches out of a murmur wrapper session, and does nothing
+# elsewhere. Deliberately not M-b or another Alt letter: a root-table binding
+# is consumed before any pane, so it would eat the picker's own M-b / M-w /
+# M-d / M-x filters -- the same class of collision that made ^b useless there.
+bind -n M-Escape if-shell -F '#{m:*~,#{session_name}}' detach-client
+```
+
+Outside tmux none of this applies: `murmur pick` runs the ssh directly, which is
+already full-screen, and you land back at your shell prompt on exit.
+
 ## Status
 
-**0.1.3.** In daily use on one machine and verified across two over real ssh.
-It is new and not battle-tested. The known gaps are listed at the end of
-[ARCHITECTURE.md](ARCHITECTURE.md#known-gaps); the one most likely to annoy you
-is that jumping to a remote agent nests tmux inside tmux, which every tool in
-this space punts on.
+**0.2.0.** 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).
 
-The event schema is versioned on the wire and preserves fields it does not
-recognise, so a newer node and an older one can already talk to each other.
+**All nodes must run the same murmur version.** The snapshot format is versioned
+and a mismatch is rejected rather than guessed at, so a node running older code
+is reported as reachable-but-broken with the reason on it — `murmur peer list`
+shows each peer's version for exactly this. Upgrade the fleet together.
 
 ## Documentation
 
-[ARCHITECTURE.md](ARCHITECTURE.md) explains how it works, the three ideas you
-need before changing anything, why it exists rather than the alternatives, and
-what is unfinished.
+[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.
 
 ---