feat: bounded auto-resume + loud exited-pane banner for crashed agent CLIs (katas 7w4h, xkhx)

crates/freshell-protocol/src/server_messages.rs

@@ -126,6 +126,8 @@ pub enum ServerMessage {
     TerminalOutputBatch(TerminalOutputBatch),
     #[serde(rename = "terminal.output.gap")]
     TerminalOutputGap(TerminalOutputGap),
+    #[serde(rename = "terminal.replaced")]
+    TerminalReplaced(TerminalReplaced),
     #[serde(rename = "terminal.session.associated")]
     TerminalSessionAssociated(TerminalSessionAssociated),
     #[serde(rename = "terminal.status")]
@@ -144,7 +146,7 @@ pub enum ServerMessage {
 
 /// The exact `type` discriminants of every server→client message, in the frozen
 /// inventory's order. This is the T0 conformance checklist.
-pub const SERVER_MESSAGE_TYPES: [&str; 56] = [
+pub const SERVER_MESSAGE_TYPES: [&str; 57] = [
     "amplifier.activity.list.response",
     "amplifier.activity.updated",
     "claude.activity.list.response",
@@ -194,6 +196,7 @@ pub const SERVER_MESSAGE_TYPES: [&str; 56] = [
     "terminal.output",
     "terminal.output.batch",
     "terminal.output.gap",
+    "terminal.replaced",
     "terminal.session.associated",
     "terminal.status",
     "terminal.stream.changed",
@@ -1061,6 +1064,16 @@ pub struct TerminalOutputGap {
     pub attach_request_id: Option<String>,
 }
 
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TerminalReplaced {
+    pub old_terminal_id: String,
+    pub new_terminal_id: String,
+    pub exit_code: i64,
+    pub attempt: u32,
+    pub max_attempts: u32,
+}
+
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct TerminalSessionAssociated {
@@ -1075,6 +1088,14 @@ pub struct TerminalStatus {
     pub terminal_id: String,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub attempt: Option<i64>,
+    /// Auto-resume `recovering` frames only: the bounded retry budget. The
+    /// client renders attempt/maxAttempts from these FIELDS — `reason` prose
+    /// is purely presentational and must never be parsed (council 7w4h/xkhx).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_attempts: Option<i64>,
+    /// Auto-resume `recovering` frames only: the crashed generation's exit code.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub exit_code: Option<i64>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub reason: Option<String>,
 }

crates/freshell-protocol/tests/inventory.rs

@@ -48,27 +48,40 @@ fn server_types_match_inventory_exactly() {
     let inv = inventory();
     assert_eq!(
         inv["serverToClient"]["count"].as_u64(),
-        Some(56),
-        "inventory declares 56 server→client types"
+        Some(57),
+        "inventory declares 57 server→client types"
     );
     let expected = json_type_set(&inv["serverToClient"]["types"]);
     let actual: BTreeSet<String> = SERVER_MESSAGE_TYPES.iter().map(|s| s.to_string()).collect();
-    assert_eq!(actual.len(), 56, "crate declares 56 server types (no dups)");
+    assert_eq!(actual.len(), 57, "crate declares 57 server types (no dups)");
     assert_eq!(
         actual, expected,
         "SERVER_MESSAGE_TYPES must equal the frozen inventory (no missing/extra)"
     );
 }
 
 #[test]
-fn combined_surface_is_85() {
+fn combined_surface_is_86() {
     let all = all_message_types();
-    assert_eq!(all.len(), 85, "29 client + 56 server = 85 discriminants");
+    assert_eq!(all.len(), 86, "29 client + 57 server = 86 discriminants");
     // sorted + unique
     let unique: BTreeSet<&str> = all.iter().copied().collect();
     assert_eq!(
         unique.len(),
-        85,
+        86,
         "no discriminant collides across directions"
     );
 }
+
+#[test]
+fn terminal_replaced_roundtrips_camel_case() {
+    let json = r#"{"type":"terminal.replaced","oldTerminalId":"t-old","newTerminalId":"t-new","exitCode":1,"attempt":1,"maxAttempts":2}"#;
+    let msg: freshell_protocol::ServerMessage = serde_json::from_str(json).expect("parse");
+    let back = serde_json::to_string(&msg).expect("serialize");
+    let v: serde_json::Value = serde_json::from_str(&back).unwrap();
+    assert_eq!(v["type"], "terminal.replaced");
+    assert_eq!(v["oldTerminalId"], "t-old");
+    assert_eq!(v["newTerminalId"], "t-new");
+    assert_eq!(v["exitCode"], 1);
+    assert_eq!(v["maxAttempts"], 2);
+}

crates/freshell-protocol/tests/roundtrip.rs

@@ -257,6 +257,19 @@ fn rich_server_messages() {
         ServerMessage::TerminalTurnComplete(t) => assert_eq!(t.provider, AgentProvider::Opencode),
         other => panic!("expected TerminalTurnComplete, got {other:?}"),
     }
+
+    // terminal.status — auto-resume `recovering` with the typed retry-budget
+    // fields (council 7w4h/xkhx: attempt/maxAttempts/exitCode are FIELDS, the
+    // reason prose is purely presentational and never parsed by the client).
+    let wire = r#"{"type":"terminal.status","status":"recovering","terminalId":"t1","attempt":1,"maxAttempts":2,"exitCode":137,"reason":"claude crashed (exit 137) — auto-resuming, attempt 1/2"}"#;
+    match server_roundtrip(wire, "terminal.status") {
+        ServerMessage::TerminalStatus(s) => {
+            assert_eq!(s.attempt, Some(1));
+            assert_eq!(s.max_attempts, Some(2));
+            assert_eq!(s.exit_code, Some(137));
+        }
+        other => panic!("expected TerminalStatus, got {other:?}"),
+    }
 }
 
 #[test]

crates/freshell-server/src/main.rs

@@ -549,7 +549,13 @@ async fn main() -> ExitCode {
     fresh_opencode_state.set_identity_sink(fresh_agent_identity_sink.clone());
     // opencode REST surface (Task 7's materialization site; V10 A13-N1)
     fresh_agent_state.set_identity_sink(fresh_agent_identity_sink.clone());
+    // Lane D1: the crash-event channel for terminal auto-resume. The receiver
+    // is consumed by `auto_resume::spawn_auto_resume_hub`, spawned right
+    // after `ws_state` is assembled (the hub needs the full state).
+    let (auto_resume_tx, auto_resume_rx) =
+        tokio::sync::mpsc::unbounded_channel::<freshell_ws::auto_resume::CrashEvent>();
     let ws_state = WsState {
+        auto_resume_tx,
         activity: Some(activity_hub.clone()),
         identity: terminal_identity.clone(),
         amplifier_locator: amplifier_locator.clone(),
@@ -627,6 +633,15 @@ async fn main() -> ExitCode {
         pane_ledger: std::sync::Arc::clone(&pane_ledger),
     };
 
+    // Lane D1 (Task 5): the auto-resume hub — consumes the crash events the
+    // PTY exit hook sends and drives bounded respawns. A boot-time background
+    // task, same precedent as `spawn_idle_monitor` above. The handle is
+    // deliberately discarded: the hub SELF-SUPERVISES (council 7w4h/xkhx,
+    // crusty) — a driver panic is caught inside the task, logged ERROR, and
+    // the loop restarted with bounded escalating backoff, so the task only
+    // ever ends when the crash-event channel closes at shutdown.
+    freshell_ws::auto_resume::spawn_auto_resume_hub(ws_state.clone(), auto_resume_rx);
+
     // P1.8 boot hygiene: quarantine, stale-marker sweep, supersession
     // repair, GC. Tombstone deletion keys on the DIRECT stat
     // (`transcript_definitively_absent`) — never on probe.exists()==Absent

crates/freshell-ws/src/amplifier_association.rs

@@ -290,6 +290,7 @@ mod tests {
                 .unwrap(),
             ),
             broadcast_tx: StdArc::clone(&broadcast_tx),
+            auto_resume_tx: tokio::sync::mpsc::unbounded_channel().0,
             fresh_codex: freshell_freshagent::FreshCodexState::new(
                 StdArc::clone(&auth_token),
                 StdArc::clone(&broadcast_tx),