@martintrojer/murmur 0.1.0 → 0.1.2

package/ARCHITECTURE.md

@@ -55,6 +55,40 @@ Two consequences worth stating, because both are easy to violate by accident:
   thing today, and differ the moment anything gossips. Free to preserve now,
   expensive to retrofit.
 
+## A tmux pane is the agent's address
+
+Everything below assumes agents run inside tmux. That assumption does real work
+in one specific way: a pane is how murmur names an agent and how a jump reaches
+one.
+
+The extension resolves its pane from `$TMUX_PANE` and returns early if there is
+none, so a pi started in a plain terminal writes no events and never appears in
+the picker. That is the honest outcome rather than a gap: with no pane there is
+no address, and a row you cannot jump to is worse than no row.
+
+Two nearby calls look contradictory and are not:
+
+- `currentWindow()` answers "which pane am I in", so only `$TMUX_PANE` can tell
+  it. Asking tmux instead reports whichever pane the server considers active,
+  which would let a non-tmux pi record itself in an unrelated agent's pane and
+  overwrite that agent's state.
+- `liveWindows()` answers "which windows exist on this host", which is
+  server-wide and correct from anywhere. Export runs over ssh with no pane of
+  its own and still has to see the windows.
+
+The remote jump inherits the same requirement, since it is `ssh -t <host> tmux
+attach`. tmux must be running on the far side, which is why a dead remote tmux
+server gets its own diagnosis rather than being reported as an unreachable
+host.
+
+The badge also has to be cleared from outside, which is why `murmur clear
+--pane <id>` exists and why tmux hooks have to call it. A window option is what
+the status bar and the `tms` session picker read, so it outlives the agent
+unless something clears it, and the agent itself cannot: "you looked at it" is
+an event only the multiplexer sees. Hooks run in the tmux server with no
+`$TMUX_PANE`, so the pane id is passed explicitly — and it must be, because the
+badge belongs to the window while the looking belongs to one pane.
+
 ## The six units
 
 | Unit | Does | Depends on |

package/README.md

@@ -66,6 +66,12 @@ against herdr, T3 Code and `mu`.
 tmux, [pi](https://github.com/earendil-works/pi-coding-agent), `fzf`, and Node
 20+. For more than one machine: ssh access, and murmur installed on each.
 
+**Agents must run inside tmux**, on every machine. A tmux pane is how murmur
+addresses an agent, so a pi started in a plain terminal records nothing and
+never appears in the picker. That is deliberate: there would be no way to jump
+to it. Remote agents need tmux on the remote too, since the jump is
+`ssh -t <host> tmux attach`.
+
 ## Install
 
 On every node that runs agents:
@@ -79,25 +85,48 @@ 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.
 
-Then, on whichever machine you want to watch from:
+Also on every node, in `.tmux.conf`, so a finished agent stops asking for
+attention once you look at it:
+
+```tmux
+set-hook -g after-select-pane      "run-shell -b 'murmur clear --pane #{pane_id}'"
+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.
+
+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.
+
+Then, on whichever machine you want to watch from, add the peers and bind the
+picker to a key:
 
 ```bash
 murmur peer add devbox   # an ssh target; identity is discovered
-murmur pick
 ```
 
-Bind it to a key and you have the whole interface:
-
 ```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
+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`.
 
 ## Status
 
-**0.1.0.** In daily use on one machine and verified across two over real ssh.
+**0.1.2.** 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

package/dist/cli.js

@@ -52,7 +52,7 @@ function runTmux(args) {
 }
 var tmux = {
   currentWindow() {
-    const pane = process.env.TMUX_PANE ?? runTmux(["display-message", "-p", "#{pane_id}"]);
+    const pane = process.env.TMUX_PANE;
     if (!pane) return null;
     const fields = runTmux([
       "display-message",
@@ -80,6 +80,12 @@ var tmux = {
   // deliberately distinct from an empty set, which means "tmux answered, and
   // there are no windows". Treating the first as the second would clear every
   // agent on the host the moment tmux was unreachable.
+  //
+  // Unlike currentWindow, this deliberately asks tmux rather than reading the
+  // environment, and it is right to: "which windows exist on this host" is a
+  // server-wide question with one answer, and export runs over ssh with no
+  // pane of its own. currentWindow asks "which pane am I in", which only
+  // $TMUX_PANE can answer.
   liveWindows() {
     const out = runTmux(["list-windows", "-a", "-F", "#{window_id}"]);
     if (out === null) return null;
@@ -112,6 +118,13 @@ var tmux = {
   },
   // First window carrying this exact name, or null. Used to reuse a per-host
   // ssh window instead of opening another one.
+  // Sibling panes, for deciding whether an unowned pane may clear the window's
+  // badge. A window holding an agent and a shell must not lose the badge when
+  // you focus the shell.
+  panesInWindow(window) {
+    const out = runTmux(["list-panes", "-t", window, "-F", "#{pane_id}"]);
+    return out?.split("\n").filter(Boolean) ?? [];
+  },
   windowNamed(name) {
     const out = runTmux(["list-windows", "-a", "-F", "#{window_id}	#{window_name}"]);
     for (const line of out?.split("\n") ?? []) {
@@ -366,6 +379,29 @@ function openStore() {
 }
 
 // src/cli/clear.ts
+function windowHasAgent(window, focused, hostId, mux) {
+  if (!hostId) return false;
+  const siblings = mux.panesInWindow(window).filter((candidate) => candidate !== focused);
+  if (siblings.length === 0) return false;
+  try {
+    const database = new Database2(dbPath(), { readonly: true, fileMustExist: true });
+    try {
+      for (const sibling of siblings) {
+        const row = database.prepare(
+          `SELECT state FROM events
+              WHERE host_id = ? AND agent_id = ?
+              ORDER BY seq DESC LIMIT 1`
+        ).get(hostId, `${hostId}:${sibling}`);
+        if (row && row.state !== "cleared") return true;
+      }
+    } finally {
+      database.close();
+    }
+    return false;
+  } catch {
+    return true;
+  }
+}
 function clearPane(pane, mux = tmux) {
   try {
     if (!pane) return;
@@ -391,10 +427,15 @@ function clearPane(pane, mux = tmux) {
       }
     }
     if (!owner) {
-      if (window) mux.setState(window, null);
+      if (window && !windowHasAgent(window, pane, identity?.host_id, mux)) {
+        mux.setState(window, null);
+      }
+      return;
+    }
+    if (owner.state === "cleared") {
+      mux.setState(owner.window, null);
       return;
     }
-    if (owner.state === "cleared") return;
     const store = openStore();
     try {
       store.append({
@@ -930,6 +971,16 @@ function forgetReplica(store, agentId, hostId) {
   } catch {
   }
 }
+function forgetOneAgent(store, agent, mux = tmux) {
+  const identity = loadIdentity();
+  if (agent.host_id === identity?.host_id) {
+    try {
+      mux.setState(agent.window, null);
+    } catch {
+    }
+  }
+  forgetReplica(store, agent.agent_id, agent.host_id);
+}
 function jumpToAgent(store, agent) {
   const identity = loadIdentity();
   if (agent.host_id === identity?.host_id) {
@@ -1163,7 +1214,7 @@ function headerRow(showHost) {
     " ".repeat(COLUMNS.glyph),
     pad("state", COLUMNS.state),
     pad("agent", COLUMNS.name),
-    pad("workstream", showHost ? COLUMNS.stream : COLUMNS.streamWide),
+    pad("stream", showHost ? COLUMNS.stream : COLUMNS.streamWide),
     showHost ? pad("host", COLUMNS.host) : "",
     "age / flags"
   ].filter(Boolean).join(" ");
@@ -1209,6 +1260,9 @@ function pad(value, width) {
   const tail = value.slice(index).match(ANSI_AT_END);
   return `${out}\u2026${tail?.[0] ?? ""}${" ".repeat(Math.max(0, width - budget - 1))}`;
 }
+function isPopup(env) {
+  return Boolean(env.TMUX) && !env.TMUX_PANE;
+}
 function pickerRow(agent, showHost, current, local = true) {
   const state = agent.state ?? "idle";
   const colour = COLOUR[state] ?? "";
@@ -1216,7 +1270,8 @@ function pickerRow(agent, showHost, current, local = true) {
   const marker = current ? `${BOLD}\u25C6${RESET}` : " ";
   const name = agent.agent_name ?? agent.pi_session ?? agentLabel(agent);
   const host = showHost ? local ? `${DIM}  here${RESET}` : `${REMOTE}\u2192 ${terminalText(agent.host)}${RESET}` : "";
-  const workstream = agent.workstream ? `${DIM}${terminalText(agent.workstream)}${RESET}` : "";
+  const group = agent.workstream ?? agent.session_name;
+  const workstream = group ? `${DIM}${terminalText(group)}${RESET}` : "";
   const flags = [
     agent.driver === "orchestrated" ? "crew" : "",
     agent.stale ? "unreachable" : "",
@@ -1297,6 +1352,8 @@ async function runPick(store, options = {}) {
   }
   const prompt = URGENCY.filter((state) => counts.get(state)).map((state) => `${COLOUR[state]}${GLYPH[state]}${counts.get(state)}${RESET}`).join(" ");
   const self = process.argv[1] ?? "murmur";
+  const allFlag = options.all ? " --all" : "";
+  const inPopup = isPopup(process.env);
   const width = process.stdout.columns ?? 0;
   const previewLayout = width > 0 && width < 150 ? "bottom:60%,border-top,wrap" : "right:58%,border-left,wrap";
   const preview = `${process.execPath} ${self} pick --preview {1}`;
@@ -1312,17 +1369,37 @@ async function runPick(store, options = {}) {
       "--with-nth",
       "2..",
       "--ansi",
-      "--no-sort",
+      // Literal substring matching, and matching only the visible columns.
+      // Default fuzzy scatters query characters across the row: `re` matched
+      // "Fix Murmur Pick Fzf Filter" as well as "recovered". A query here is a
+      // word or two of an agent or workstream name, so substring is what the
+      // fingers expect. Prefix a token with ' to opt back into fuzzy.
+      // Same choice as the tms session picker, for consistency across the two.
+      "--exact",
+      // `begin` ranks earlier match positions higher, so `scratch` puts the
+      // scratch workstream above a row that merely mentions it. `index` is the
+      // empty-query fallback and preserves the attention order the fold
+      // produced, which is the whole point of the list.
+      "--tiebreak",
+      "begin,index",
       "--layout",
       "reverse",
+      // `display-popup` draws its own border, so fzf's is a second one a
+      // character inside the first. A popup is the normal way to run this, via
+      // the prefix+a binding, so the doubled frame was what you saw most.
+      //
+      // Detected by $TMUX set with $TMUX_PANE unset: tmux exports TMUX to a
+      // popup but not TMUX_PANE, since a popup is not a pane. Outside tmux
+      // neither is set, so the three cases stay distinguishable.
       "--border",
+      inPopup ? "none" : "rounded",
       "--info",
       "inline",
       "--prompt",
       `${prompt}${prompt ? "  " : ""}`,
       "--header",
       [
-        `enter jump   ctrl-r refresh   ctrl-p preview   filter: ${FILTER_KEYS.map(
+        `enter jump   ^r refresh   ^p preview   del forget   filter: ${FILTER_KEYS.map(
           ([key, state]) => `${key.replace("ctrl-", "^")} ${state || "all"}`
         ).join(" ")}`,
         hidden ? `${hidden} crew hidden (--all)` : "",
@@ -1339,7 +1416,17 @@ async function runPick(store, options = {}) {
       "--bind",
       "ctrl-p:change-preview-window(bottom:60%,border-top,wrap|hidden|right:58%,border-left,wrap)",
       "--bind",
-      `ctrl-r:reload(${process.execPath} ${self} pick --rows${options.all ? " --all" : ""})`,
+      `ctrl-r:reload(${process.execPath} ${self} pick --rows${allFlag})`,
+      // Manual dismissal for a row nothing else will clear.
+      //
+      // The delete key, not a ctrl chord. ctrl-shift-d does not exist -- a
+      // terminal sends the same bytes as ctrl-d -- and ctrl-alt-d, while it
+      // does dispatch distinctly, sits one modifier away from ctrl-d in a
+      // header that lists both. One is a filter and the other destroys a row,
+      // so a near-miss is a deleted agent. `delete` is the key that already
+      // means remove this, and it collides with no filter letter.
+      "--bind",
+      `delete:reload(${process.execPath} ${self} pick --forget {1}${allFlag})`,
       ...filterBinds,
       "--no-select-1",
       "--no-exit-0"
@@ -1366,6 +1453,12 @@ async function runPick(store, options = {}) {
     process.exitCode = 1;
   }
 }
+async function runForget(store, agentId, options = {}) {
+  const view = status(store);
+  const agent = view.agents.find((candidate) => candidate.agent_id === agentId);
+  if (agent) forgetOneAgent(store, agent);
+  await runRows(store, options);
+}
 async function runRows(store, options = {}) {
   const identity = loadIdentity();
   const view = await statusWithCollect(store);
@@ -1380,16 +1473,19 @@ async function runRows(store, options = {}) {
   }
 }
 function registerPick(program2) {
-  program2.command("pick").description("Pick an agent and jump to it").option("--all", "include orchestrated agents").option("--preview <agent-id>", "render the preview pane for one agent (internal)").option("--rows", "print picker rows only (internal, for reload)").action(async (options) => {
-    const store = openStore();
-    try {
-      if (options.preview) runPreview(store, options.preview);
-      else if (options.rows) await runRows(store, options);
-      else await runPick(store, options);
-    } finally {
-      store.close();
+  program2.command("pick").description("Pick an agent and jump to it").option("--all", "include orchestrated agents").option("--preview <agent-id>", "render the preview pane for one agent (internal)").option("--rows", "print picker rows only (internal, for reload)").option("--forget <agent-id>", "drop one agent, then print rows (internal)").action(
+    async (options) => {
+      const store = openStore();
+      try {
+        if (options.preview) runPreview(store, options.preview);
+        else if (options.forget) await runForget(store, options.forget, options);
+        else if (options.rows) await runRows(store, options);
+        else await runPick(store, options);
+      } finally {
+        store.close();
+      }
     }
-  });
+  );
 }
 
 // src/cli/status.ts
@@ -1409,7 +1505,9 @@ function registerStatus(program2) {
 }
 
 // src/index.ts
-var VERSION = "0.1.0";
+import { createRequire } from "module";
+var manifest = createRequire(import.meta.url)("../package.json");
+var VERSION = manifest.version;
 
 // src/cli.ts
 var program = new Command();