fix(terminal): Correct background output rendering

- Replay control sequences at source PTY dimensions to fix ConPTY
  wrapping, duplicated characters, and cursor overwrites
- Report local and SSH terminal dimensions, support legacy metadata,
  and flag incomplete replay
- Separate replay from display while preserving colors, log reflow,
  and raw output copying
- Serialize polling, discard stale session responses, and drain
  remaining output after completion
- Fix bottom whitespace, black strips, and lost rows under scaling
- Remove the simplified display option and use colored output throughout
- Blend command card footers into the Ink Charm theme
- Fix @xterm/headless entry resolution and add regression coverage
  for replay, terminal sizing, and metadata compatibility

Refs: #2208

Author: wsp1911

design-system/packages/ui/src/flow-chat/tool-cards/CommandToolCard.module.css

@@ -143,7 +143,7 @@
     padding-inline: var(--openbitfun-space-3);
     border-radius: var(--openbitfun-radius-sm);
     color: var(--openbitfun-color-content-muted);
-    background: var(--openbitfun-color-surface-raised);
+    background: transparent;
     font-size: var(--openbitfun-type-body-sm-font-size);
   }
 

pnpm-lock.yaml

@@ -558,6 +558,7 @@ impl ExecCommandTool {
                         workdir: Some(workdir.clone()),
                         remote: true,
                         tty,
+                        terminal_size: remote_exec_port.exec_terminal_size(),
                     })
                     .await,
             )
@@ -833,6 +834,7 @@ Output:
                         workdir: Some(workdir.to_string_lossy().to_string()),
                         remote: false,
                         tty,
+                        terminal_size: terminal_port.exec_terminal_size(),
                     })
                     .await,
             )

src/crates/assembly/core/src/agentic/tools/implementations/exec_command/command.rs

@@ -85,6 +85,13 @@ pub use web_search::*;
 
 pub type PortResult<T> = Result<T, PortError>;
 
+/// Source geometry for a fixed-size ExecCommand PTY replay.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ExecTerminalSize {
+    pub cols: u16,
+    pub rows: u16,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum PortErrorKind {

src/crates/contracts/runtime-ports/src/lib.rs

@@ -117,6 +117,11 @@ pub type RemoteExecOutputSink = mpsc::UnboundedSender<String>;
 pub type RemoteExecStreamingOutputSink = mpsc::Sender<String>;
 #[async_trait::async_trait]
 pub trait RemoteExecPort: RuntimeServicePort + std::fmt::Debug {
+    /// None means the provider cannot guarantee a fixed replay geometry.
+    fn exec_terminal_size(&self) -> Option<ExecTerminalSize> {
+        None
+    }
+
     /// Authoritative liveness query for a remote ExecCommand session.
     async fn is_session_active(&self, _session_id: i32) -> PortResult<bool> {
         Ok(false)

src/crates/contracts/runtime-ports/src/remote_exec_port.rs

@@ -105,6 +105,11 @@ pub type TerminalExecStreamingOutputSink = mpsc::Sender<String>;
 
 #[async_trait::async_trait]
 pub trait TerminalPort: RuntimeServicePort + std::fmt::Debug {
+    /// None means the provider cannot guarantee a fixed replay geometry.
+    fn exec_terminal_size(&self) -> Option<ExecTerminalSize> {
+        None
+    }
+
     /// Authoritative liveness query for an ExecCommand session.
     /// Providers that cannot inspect state fail closed.
     async fn is_session_active(&self, _session_id: i32) -> PortResult<bool> {

src/crates/contracts/runtime-ports/src/terminal_port.rs

@@ -1,4 +1,5 @@
-use serde::Serialize;
+use openbitfun_runtime_ports::ExecTerminalSize;
+use serde::{Deserialize, Serialize};
 use std::collections::{HashMap, VecDeque};
 use std::sync::{Arc, OnceLock};
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
@@ -18,7 +19,7 @@ pub fn background_command_output_capture() -> Arc<BackgroundCommandOutputCapture
         .clone()
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum BackgroundCommandOutputStatus {
     Running,
@@ -35,7 +36,7 @@ struct BackgroundCommandSessionKey {
     exec_session_id: i32,
 }
 
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct BackgroundCommandOutputMetadata {
     pub agent_session_id: Option<String>,
@@ -44,6 +45,9 @@ pub struct BackgroundCommandOutputMetadata {
     pub workdir: Option<String>,
     pub remote: bool,
     pub tty: bool,
+    /// Explicit null means unknown geometry; absent on older hosts.
+    #[serde(default)]
+    pub terminal_size: Option<ExecTerminalSize>,
     pub status: BackgroundCommandOutputStatus,
     pub exit_code: Option<i32>,
     pub started_at: u64,
@@ -62,6 +66,7 @@ pub struct StartBackgroundCommandOutputCapture {
     pub workdir: Option<String>,
     pub remote: bool,
     pub tty: bool,
+    pub terminal_size: Option<ExecTerminalSize>,
 }
 
 #[derive(Debug, Clone)]
@@ -104,6 +109,7 @@ struct BackgroundCommandOutputRecord {
     workdir: Option<String>,
     remote: bool,
     tty: bool,
+    terminal_size: Option<ExecTerminalSize>,
     exec_session_id: Option<i32>,
     status: BackgroundCommandOutputStatus,
     exit_code: Option<i32>,
@@ -135,6 +141,7 @@ impl BackgroundCommandOutputCapture {
             workdir: request.workdir,
             remote: request.remote,
             tty: request.tty,
+            terminal_size: request.terminal_size.filter(|_| request.tty),
             exec_session_id: None,
             status: BackgroundCommandOutputStatus::Running,
             exit_code: None,
@@ -413,6 +420,7 @@ impl BackgroundCommandOutputRecord {
             workdir: self.workdir.clone(),
             remote: self.remote,
             tty: self.tty,
+            terminal_size: self.terminal_size,
             status: self.status,
             exit_code: self.exit_code,
             started_at: self.started_at,
@@ -466,6 +474,34 @@ mod tests {
         ReadBackgroundCommandOutputRequest, StartBackgroundCommandOutputCapture,
     };
 
+    #[test]
+    fn background_output_metadata_reads_legacy_payload_and_round_trips_geometry() {
+        let legacy = serde_json::json!({
+            "agentSessionId": null, "execSessionId": 42, "command": "test",
+            "workdir": null, "remote": true, "tty": true, "status": "running",
+            "exitCode": null, "startedAt": 0, "endedAt": null,
+            "retainedBytes": 0, "retainedLimitBytes": 1048576, "truncatedFromStart": false
+        });
+        let mut metadata: super::BackgroundCommandOutputMetadata =
+            serde_json::from_value(legacy.clone()).unwrap();
+        assert_eq!(metadata.terminal_size, None);
+        let old_round_trip = serde_json::to_value(&metadata).unwrap();
+        for (key, value) in legacy.as_object().unwrap() {
+            assert_eq!(&old_round_trip[key], value);
+        }
+        // New hosts explicitly distinguish unknown geometry from old absent fields.
+        assert!(old_round_trip["terminalSize"].is_null());
+        metadata.terminal_size = Some(super::ExecTerminalSize { cols: 80, rows: 24 });
+        let encoded = serde_json::to_value(&metadata).unwrap();
+        assert_eq!(
+            encoded["terminalSize"],
+            serde_json::json!({"cols": 80, "rows": 24})
+        );
+        let restored: super::BackgroundCommandOutputMetadata =
+            serde_json::from_value(encoded).unwrap();
+        assert_eq!(restored.terminal_size, metadata.terminal_size);
+    }
+
     #[tokio::test]
     async fn background_command_output_reads_snapshot_then_incremental_chunks() {
         let capture_id = format!(
@@ -484,6 +520,7 @@ mod tests {
                 workdir: None,
                 remote: false,
                 tty: false,
+                terminal_size: None,
             })
             .await;
 

src/crates/execution/tool-execution/src/background_command_output.rs

@@ -19,6 +19,8 @@ use tokio::time::{Duration, Instant};
 use uuid::Uuid;
 
 const DEFAULT_YIELD_TIME_MS: u64 = 10_000;
+pub(super) const EXEC_TERMINAL_SIZE: openbitfun_runtime_ports::ExecTerminalSize =
+    openbitfun_runtime_ports::ExecTerminalSize { cols: 80, rows: 24 };
 const MAX_RETAINED_OUTPUT_BYTES: usize = 1024 * 1024;
 const MAX_REMOTE_EXEC_SESSIONS: usize = 64;
 const MAX_COMPLETED_REMOTE_EXEC_SESSIONS: usize = 64;
@@ -739,8 +741,14 @@ async fn spawn_local_workspace_pty_process(
             .try_into()
             .expect("UUID prefix is four bytes"),
     );
-    let spawned = spawn_pty(process_id, &shell_config, shell_type, 80, 24)
-        .map_err(|error| anyhow!("Failed to start local workspace PTY: {}", error))?;
+    let spawned = spawn_pty(
+        process_id,
+        &shell_config,
+        shell_type,
+        EXEC_TERMINAL_SIZE.cols,
+        EXEC_TERMINAL_SIZE.rows,
+    )
+    .map_err(|error| anyhow!("Failed to start local workspace PTY: {}", error))?;
     let output = Arc::new(OutputState::new(request.output_capture_tx.clone()));
     let (command_tx, mut command_rx) = mpsc::channel::<RemoteExecProcessCommand>(64);
     let owner_output = output.clone();
@@ -816,7 +824,12 @@ async fn spawn_remote_pty_process(
 ) -> anyhow::Result<RemoteExecProcess> {
     let channel = request
         .ssh_manager
-        .open_pty_exec_channel(&request.connection_id, &request.command, 80, 24)
+        .open_pty_exec_channel(
+            &request.connection_id,
+            &request.command,
+            EXEC_TERMINAL_SIZE.cols.into(),
+            EXEC_TERMINAL_SIZE.rows.into(),
+        )
         .await?;
     let output = Arc::new(OutputState::new(request.output_capture_tx.clone()));
     let (command_tx, command_rx) = mpsc::channel::<RemoteExecProcessCommand>(64);

src/crates/services/services-integrations/src/remote_ssh/remote_exec.rs

@@ -72,6 +72,10 @@ impl ports::RuntimeServicePort for RemoteExecRuntimePort {
 
 #[async_trait]
 impl ports::RemoteExecPort for RemoteExecRuntimePort {
+    fn exec_terminal_size(&self) -> Option<ports::ExecTerminalSize> {
+        Some(super::remote_exec::EXEC_TERMINAL_SIZE)
+    }
+
     async fn is_session_active(&self, session_id: i32) -> ports::PortResult<bool> {
         Ok(self.manager.is_session_active(session_id).await)
     }

src/crates/services/services-integrations/src/remote_ssh/remote_exec_runtime_port.rs

@@ -23,6 +23,8 @@ use tokio::task::JoinHandle;
 use uuid::Uuid;
 
 const DEFAULT_YIELD_TIME_MS: u64 = 10_000;
+pub(crate) const EXEC_TERMINAL_SIZE: openbitfun_runtime_ports::ExecTerminalSize =
+    openbitfun_runtime_ports::ExecTerminalSize { cols: 80, rows: 24 };
 const MAX_RETAINED_OUTPUT_BYTES: usize = 1024 * 1024;
 const MAX_EXEC_SESSIONS: usize = 64;
 const MAX_COMPLETED_EXEC_SESSIONS: usize = 64;
@@ -1097,8 +1099,8 @@ async fn spawn_exec_process(
 async fn spawn_pty_process(request: &ExecCommandRequest) -> TerminalResult<ExecProcess> {
     let pty_system = native_pty_system();
     let pair = pty_system.openpty(PtySize {
-        rows: 24,
-        cols: 80,
+        rows: EXEC_TERMINAL_SIZE.rows,
+        cols: EXEC_TERMINAL_SIZE.cols,
         pixel_width: 0,
         pixel_height: 0,
     })?;