Add binary server event journal

README.md

@@ -208,6 +208,9 @@ For wire protocol details, frame encoding, and transport internals, see [ARCHITE
 | `BLIT_TARGET`            | unset                                                                                                              | Default remote: a URI or named remote (overrides `target` in `blit.conf`)                                                                                                                                                                 |
 | `BLIT_REMOTES`           | `~/.config/blit/blit.remotes`                                                                                      | Gateway remotes file path (overrides default location)                                                                                                                                                                                    |
 | `BLIT_SCROLLBACK`        | `10000`                                                                                                            | Scrollback rows per PTY                                                                                                                                                                                                                   |
+| `BLIT_EVENTS_SIZE`       | `1048576`                                                                                                          | Binary server event-ring capacity                                                                                                                                                                                                         |
+| `BLIT_EVENTS`            | low-throughput lifecycle events                                                                                    | Fine-grained event names/selectors (`default,+frame.*,+pty.*`, or `all`)                                                                                                                                                                  |
+| `BLIT_EVENTS_FILE`       | unset                                                                                                              | Stream binary events to this server-side file from startup                                                                                                                                                                                |
 | `BLIT_HUB`               | `hub.blit.sh`                                                                                                      | Signaling hub URL for WebRTC sharing. On `blit gateway`, sets the default hub for `share:` remotes when `BLIT_GATEWAY_WEBRTC=1`.                                                                                                          |
 | `BLIT_GATEWAY_WEBRTC`    | unset                                                                                                              | Set to `1` on `blit gateway` to proxy `share:` remotes via WebRTC. The gateway connects as a WebRTC consumer and bridges terminals to browsers over WebSocket/WebTransport. Without this, `share:` entries in `blit.remotes` are ignored. |
 | `BLIT_PASSPHRASE`        | unset                                                                                                              | Browser passphrase for `blit gateway`; may be plaintext or an argon2 PHC hash generated by `blit hash-passphrase`. Browsers still enter the plaintext passphrase.                                                                         |

crates/cli/src/agent.rs

@@ -218,6 +218,16 @@ impl AgentConn {
         Ok(data)
     }
 
+    pub(crate) async fn recv_unbounded(&mut self) -> Result<Vec<u8>, String> {
+        let data = read_message(&mut self.reader, &mut self.fragment_buf)
+            .await
+            .ok_or_else(|| "server closed connection".to_string())?;
+        if let Some(error) = self.note_kick(&data) {
+            return Err(error);
+        }
+        Ok(data)
+    }
+
     pub(crate) fn has_pty(&self, id: u16) -> bool {
         self.ptys.iter().any(|p| p.id == id)
     }

crates/cli/src/cli.rs

@@ -323,6 +323,12 @@ pub enum Command {
         command: Option<ClientCommand>,
     },
 
+    /// Inspect and configure the server's binary event journal
+    Events {
+        #[command(subcommand)]
+        command: EventsCommand,
+    },
+
     /// Manage compositor surfaces
     #[command(alias = "s")]
     Surface {
@@ -671,6 +677,93 @@ pub enum Command {
     External(Vec<String>),
 }
 
+// ── Event journal subcommands ────────────────────────────────────────────
+
+#[derive(Subcommand)]
+pub enum EventsCommand {
+    /// Show config revision, ring use/loss counters, and active event types
+    Config,
+
+    /// Replace ring size and/or activation bitset
+    Set {
+        /// Ring capacity in bytes (4 KiB through just under 64 MiB)
+        #[arg(long)]
+        size: Option<u64>,
+
+        /// Activation selectors: default, all, none, exact names, category.*,
+        /// with optional + or - prefixes
+        #[arg(long, value_name = "SPEC")]
+        events: Option<String>,
+
+        /// Apply only while the server configuration is still at this revision
+        #[arg(long, value_name = "REVISION")]
+        if_revision: Option<u64>,
+    },
+
+    /// Write one retained binary snapshot to stdout or a local file
+    Dump {
+        /// Local output path; defaults to stdout. Use - for stdout explicitly.
+        #[arg(short, long, value_name = "LOCAL_PATH")]
+        output: Option<String>,
+    },
+
+    /// Follow events in the foreground, writing stdout or a local file
+    ///
+    /// The stream ends with this client connection. A connection may own at
+    /// most four concurrent event tails.
+    Tail {
+        /// Local output path; defaults to stdout. Use - for stdout explicitly.
+        #[arg(short, long, value_name = "LOCAL_PATH")]
+        output: Option<String>,
+
+        /// Append to --output instead of truncating it
+        #[arg(long, requires = "output")]
+        append: bool,
+
+        /// Follow only events produced after this command starts
+        #[arg(long)]
+        from_now: bool,
+    },
+
+    /// Manage detached recordings written by the server
+    Record {
+        #[command(subcommand)]
+        command: EventsRecordCommand,
+    },
+}
+
+#[derive(Subcommand)]
+pub enum EventsRecordCommand {
+    /// Start a detached recording to a path on the server
+    ///
+    /// Returns an ID only after the initial header/history has been flushed.
+    /// The server permits at most eight detached recordings process-wide.
+    Start {
+        /// Destination path on the server
+        #[arg(value_name = "SERVER_PATH")]
+        path: String,
+
+        /// Append instead of truncating the server file
+        #[arg(long)]
+        append: bool,
+
+        /// Record only events produced after this command starts
+        #[arg(long)]
+        from_now: bool,
+    },
+
+    /// List recordings as TSV: ID, STATE, RECORDS, BYTES, LOST, HISTORY, MODE, PATH, ERROR
+    List,
+
+    /// Stop and flush a server recording
+    ///
+    /// Returns an error if any recording write or final flush failed.
+    Stop {
+        /// Recording ID from `blit events record start` or `list`
+        id: u32,
+    },
+}
+
 // ── Terminal subcommands ─────────────────────────────────────────────────
 
 #[derive(Subcommand)]