diff --git a/Resources/shell-integration/fish/config.fish b/Resources/shell-integration/fish/config.fish
new file mode 100644
index 00000000..92787430
--- /dev/null
+++ b/Resources/shell-integration/fish/config.fish
@@ -0,0 +1,396 @@
+# programa shell integration for fish
+# Injected automatically — do not source manually
+
+set -l _cmux_integration_enabled 1
+if set -q PROGRAMA_SHELL_INTEGRATION; and test "$PROGRAMA_SHELL_INTEGRATION" = 0
+    set _cmux_integration_enabled 0
+end
+
+function _cmux_restore_scrollback_once
+    set -l path "$PROGRAMA_RESTORE_SCROLLBACK_FILE"
+    test -n "$path"; or return 0
+    set -e PROGRAMA_RESTORE_SCROLLBACK_FILE
+
+    if test -r "$path"
+        /bin/cat -- "$path" 2>/dev/null
+        /bin/rm -f -- "$path" >/dev/null 2>&1
+    end
+end
+_cmux_restore_scrollback_once
+
+if test "$_cmux_integration_enabled" != 0
+    set -g _CMUX_SEND_TOOL ""
+    if command -sq ncat
+        set -g _CMUX_SEND_TOOL ncat
+    else if command -sq socat
+        set -g _CMUX_SEND_TOOL socat
+    else if command -sq nc
+        set -g _CMUX_SEND_TOOL nc
+    end
+
+    set -g _PROGRAMA_SHELL_ACTIVITY_LAST ""
+    set -g _PROGRAMA_PORTS_LAST_RUN 0
+    set -g _PROGRAMA_TTY_NAME ""
+    set -g _PROGRAMA_TTY_REPORTED 0
+    set -g _PROGRAMA_TMUX_PUSH_SIGNATURE ""
+    set -g _PROGRAMA_TMUX_PULL_SIGNATURE ""
+    set -g _PROGRAMA_TMUX_SYNC_KEYS \
+        PROGRAMA_BUNDLED_CLI_PATH \
+        PROGRAMA_BUNDLE_ID \
+        CMUXD_UNIX_PATH \
+        CMUXTERM_REPO_ROOT \
+        PROGRAMA_DEBUG_LOG \
+        PROGRAMA_PORT \
+        PROGRAMA_PORT_END \
+        PROGRAMA_PORT_RANGE \
+        PROGRAMA_REMOTE_DAEMON_ALLOW_LOCAL_BUILD \
+        PROGRAMA_SHELL_INTEGRATION \
+        PROGRAMA_SHELL_INTEGRATION_DIR \
+        PROGRAMA_SOCKET_ENABLE \
+        PROGRAMA_SOCKET_MODE \
+        PROGRAMA_SOCKET_PATH \
+        PROGRAMA_TAB_ID \
+        PROGRAMA_TAG \
+        PROGRAMA_WORKSPACE_ID
+    set -g _PROGRAMA_TMUX_SURFACE_SCOPED_KEYS PROGRAMA_PANEL_ID PROGRAMA_SURFACE_ID
+
+    function _cmux_now
+        if set -q EPOCHSECONDS
+            printf '%s\n' "$EPOCHSECONDS"
+        else
+            date +%s
+        end
+    end
+
+    function _cmux_socket_is_unix
+        test -n "$PROGRAMA_SOCKET_PATH"; and test -S "$PROGRAMA_SOCKET_PATH"
+    end
+
+    function _cmux_relay_cli_path
+        if test -n "$PROGRAMA_BUNDLED_CLI_PATH"; and test -x "$PROGRAMA_BUNDLED_CLI_PATH"
+            printf '%s\n' "$PROGRAMA_BUNDLED_CLI_PATH"
+            return 0
+        end
+        # Rebranded CLI binary ships as "programa"; fall back to the pre-rebrand
+        # "cmux" name for older installs that only symlinked that binary.
+        command -v programa 2>/dev/null; or command -v cmux 2>/dev/null
+    end
+
+    function _cmux_socket_uses_remote_relay
+        test -n "$PROGRAMA_SOCKET_PATH"; or return 1
+        string match -q '/*' -- "$PROGRAMA_SOCKET_PATH"; and return 1
+        string match -q '*:*' -- "$PROGRAMA_SOCKET_PATH"; or return 1
+        set -l relay_cli (_cmux_relay_cli_path)
+        test -n "$relay_cli"
+    end
+
+    function _cmux_has_port_scan_transport
+        _cmux_socket_is_unix; and return 0
+        _cmux_socket_uses_remote_relay
+    end
+
+    function _cmux_send --argument-names payload
+        test -n "$payload"; or return 0
+        test -n "$PROGRAMA_SOCKET_PATH"; or return 0
+        switch "$_CMUX_SEND_TOOL"
+            case ncat
+                printf '%s\n' "$payload" | ncat -w 1 -U "$PROGRAMA_SOCKET_PATH" --send-only >/dev/null 2>&1
+            case socat
+                printf '%s\n' "$payload" | socat -T 1 - "UNIX-CONNECT:$PROGRAMA_SOCKET_PATH" >/dev/null 2>&1
+            case nc
+                printf '%s\n' "$payload" | nc -N -U "$PROGRAMA_SOCKET_PATH" >/dev/null 2>&1; or printf '%s\n' "$payload" | nc -w 1 -U "$PROGRAMA_SOCKET_PATH" >/dev/null 2>&1
+        end
+    end
+
+    function _cmux_send_bg --argument-names payload
+        _cmux_send "$payload" >/dev/null 2>&1 &
+    end
+
+    function _cmux_json_escape --argument-names value
+        set -l backslash "\\"
+        set -l escaped_backslash "\\\\"
+        set -l quote '"'
+        set -l escaped_quote '\"'
+        string replace -a "$backslash" "$escaped_backslash" -- "$value" \
+            | string replace -a "$quote" "$escaped_quote" \
+            | string replace -a (printf '\n') "\\n" \
+            | string replace -a (printf '\r') "\\r" \
+            | string replace -a (printf '\t') "\\t"
+    end
+
+    # Build a single-line v2 JSON-RPC request frame for the direct-socket
+    # (fire-and-forget) path. `params_json` must already be a well-formed JSON
+    # object string (call sites use _cmux_json_escape on any user-controlled
+    # values before interpolating them).
+    function _cmux_json_rpc_frame --argument-names method params_json
+        printf '%s\n' "{\"id\":1,\"method\":\"$method\",\"params\":$params_json}"
+    end
+
+    function _cmux_relay_workspace_id
+        if test -n "$PROGRAMA_WORKSPACE_ID"
+            printf '%s\n' "$PROGRAMA_WORKSPACE_ID"
+            return 0
+        end
+        test -n "$PROGRAMA_TAB_ID"; or return 1
+        printf '%s\n' "$PROGRAMA_TAB_ID"
+    end
+
+    function _cmux_relay_rpc_bg --argument-names method params
+        _cmux_socket_uses_remote_relay; or return 1
+        set -l relay_cli (_cmux_relay_cli_path)
+        test -n "$relay_cli"; or return 1
+        "$relay_cli" rpc "$method" "$params" >/dev/null 2>&1 &
+    end
+
+    function _cmux_relay_rpc --argument-names method params
+        _cmux_socket_uses_remote_relay; or return 1
+        set -l relay_cli (_cmux_relay_cli_path)
+        test -n "$relay_cli"; or return 1
+        # Relay `programa rpc` exits nonzero on server error. The real remote CLI
+        # prints only the JSON result payload on success, while some test stubs
+        # return the full `{"ok":...}` envelope. Retry only on explicit `ok:false`.
+        set -l response ("$relay_cli" rpc "$method" "$params" 2>/dev/null | string collect)
+        test -n "$response"; or return 0
+        string match -q '*"ok":false*' -- "$response"; and return 1
+        string match -q '*"ok": false*' -- "$response"; and return 1
+        return 0
+    end
+
+    function _cmux_report_tty_via_relay
+        _cmux_socket_uses_remote_relay; or return 1
+        set -l workspace_id (_cmux_relay_workspace_id); or return 1
+        test -n "$_PROGRAMA_TTY_NAME"; or return 1
+        set -l tty_name_json (_cmux_json_escape "$_PROGRAMA_TTY_NAME")
+        set -l params "{\"workspace_id\":\"$workspace_id\",\"tty_name\":\"$tty_name_json\""
+        if test -n "$PROGRAMA_PANEL_ID"
+            set params "$params,\"surface_id\":\"$PROGRAMA_PANEL_ID\""
+        end
+        set params "$params}"
+        _cmux_relay_rpc "surface.report_tty" "$params"
+    end
+
+    function _cmux_report_tty_payload
+        test -n "$PROGRAMA_TAB_ID"; or return 1
+        test -n "$_PROGRAMA_TTY_NAME"; or return 1
+        set -l workspace_id (_cmux_relay_workspace_id)
+        test -n "$workspace_id"; or set workspace_id "$PROGRAMA_TAB_ID"
+        set -l tty_name_json (_cmux_json_escape "$_PROGRAMA_TTY_NAME")
+        set -l params "{\"workspace_id\":\"$workspace_id\",\"tty_name\":\"$tty_name_json\""
+        if test -z "$TMUX"
+            test -n "$PROGRAMA_PANEL_ID"; or return 1
+            set params "$params,\"surface_id\":\"$PROGRAMA_PANEL_ID\""
+        end
+        set params "$params}"
+        _cmux_json_rpc_frame "surface.report_tty" "$params"
+    end
+
+    function _cmux_report_tty_once
+        # Send the TTY name to the app once per session so the batched port
+        # scanner knows which TTY belongs to this panel.
+        test "$_PROGRAMA_TTY_REPORTED" = 1; and return 0
+        _cmux_has_port_scan_transport; or return 0
+
+        if _cmux_socket_is_unix
+            set -l payload (_cmux_report_tty_payload)
+            test -n "$payload"; or return 0
+            set -g _PROGRAMA_TTY_REPORTED 1
+            _cmux_send_bg "$payload"
+        else
+            test -n "$_PROGRAMA_TTY_NAME"; or return 0
+            # Keep the first relay TTY report synchronous so the server can
+            # resolve the target surface before command-start kicks begin.
+            _cmux_report_tty_via_relay; or return 0
+            set -g _PROGRAMA_TTY_REPORTED 1
+        end
+    end
+
+    function _cmux_report_shell_activity_state --argument-names state
+        test -n "$state"; or return 0
+        _cmux_socket_is_unix; or return 0
+        test -n "$PROGRAMA_TAB_ID"; or return 0
+        test -n "$PROGRAMA_PANEL_ID"; or return 0
+        test "$_PROGRAMA_SHELL_ACTIVITY_LAST" = "$state"; and return 0
+        set -g _PROGRAMA_SHELL_ACTIVITY_LAST "$state"
+        set -l workspace_id (_cmux_relay_workspace_id)
+        test -n "$workspace_id"; or set workspace_id "$PROGRAMA_TAB_ID"
+        set -l state_json (_cmux_json_escape "$state")
+        set -l params "{\"workspace_id\":\"$workspace_id\",\"surface_id\":\"$PROGRAMA_PANEL_ID\",\"state\":\"$state_json\"}"
+        _cmux_send_bg (_cmux_json_rpc_frame "surface.report_shell_state" "$params")
+    end
+
+    function _cmux_ports_kick_via_relay --argument-names reason
+        _cmux_socket_uses_remote_relay; or return 1
+        set -l workspace_id (_cmux_relay_workspace_id); or return 1
+        test -n "$reason"; or set reason command
+        set -l params "{\"workspace_id\":\"$workspace_id\",\"reason\":\"$reason\""
+        if test -n "$PROGRAMA_PANEL_ID"
+            set params "$params,\"surface_id\":\"$PROGRAMA_PANEL_ID\""
+        end
+        set params "$params}"
+        _cmux_relay_rpc_bg "surface.ports_kick" "$params"
+    end
+
+    function _cmux_ports_kick --argument-names reason
+        test -n "$reason"; or set reason command
+        # Lightweight: just tell the app to run a batched scan for this panel.
+        # The app coalesces kicks across all panels and runs a single ps+lsof.
+        _cmux_has_port_scan_transport; or return 0
+        test -n "$PROGRAMA_TAB_ID"; or return 0
+        if _cmux_socket_is_unix
+            test -n "$PROGRAMA_PANEL_ID"; or return 0
+        end
+        set -g _PROGRAMA_PORTS_LAST_RUN (_cmux_now)
+        if _cmux_socket_is_unix
+            set -l workspace_id (_cmux_relay_workspace_id)
+            test -n "$workspace_id"; or set workspace_id "$PROGRAMA_TAB_ID"
+            set -l reason_json (_cmux_json_escape "$reason")
+            set -l params "{\"workspace_id\":\"$workspace_id\",\"surface_id\":\"$PROGRAMA_PANEL_ID\",\"reason\":\"$reason_json\"}"
+            _cmux_send_bg (_cmux_json_rpc_frame "surface.ports_kick" "$params")
+        else
+            _cmux_ports_kick_via_relay "$reason"
+        end
+    end
+
+    function _cmux_reset_terminal_keyboard_protocols
+        isatty stdout; or test -n "$PROGRAMA_TEST_FORCE_KEYBOARD_RESET$PROGRAMA_TEST_FORCE_KITTY_RESET"; or return 0
+        printf '\033[>m\033[<8u'
+    end
+
+    function _cmux_tmux_sync_key_is_managed --argument-names candidate
+        contains -- "$candidate" $_PROGRAMA_TMUX_SYNC_KEYS
+    end
+
+    function _cmux_tmux_shell_env_signature
+        set -l parts
+        for key in $_PROGRAMA_TMUX_SYNC_KEYS
+            set -l value $$key
+            test -n "$value"; or continue
+            set -a parts "$key=$value"
+        end
+        string join \x1f -- $parts
+    end
+
+    function _cmux_tmux_publish_cmux_environment
+        test -z "$TMUX"; or return 0
+        command -sq tmux; or return 0
+
+        set -l signature (_cmux_tmux_shell_env_signature)
+        test -n "$signature"; or return 0
+        test "$signature" != "$_PROGRAMA_TMUX_PUSH_SIGNATURE"; or return 0
+
+        for key in $_PROGRAMA_TMUX_SYNC_KEYS
+            set -l value $$key
+            test -n "$value"; or continue
+            tmux set-environment -g "$key" "$value" >/dev/null 2>&1; or return 0
+        end
+        for key in $_PROGRAMA_TMUX_SURFACE_SCOPED_KEYS
+            tmux set-environment -gu "$key" >/dev/null 2>&1; or return 0
+        end
+
+        set -g _PROGRAMA_TMUX_PUSH_SIGNATURE "$signature"
+    end
+
+    function _cmux_tmux_refresh_cmux_environment
+        test -n "$TMUX"; or return 0
+        command -sq tmux; or return 0
+
+        set -l output (tmux show-environment -g 2>/dev/null)
+        test -n "$output"; or return 0
+
+        set -l filtered
+        for line in $output
+            string match -q 'PROGRAMA_*' -- "$line"; or continue
+            set -l key (string split -m 1 = -- "$line")[1]
+            _cmux_tmux_sync_key_is_managed "$key"; or continue
+            set -a filtered "$line"
+        end
+        test -n "$filtered"; or return 0
+        set -l joined (string join \n -- $filtered)
+        test "$joined" != "$_PROGRAMA_TMUX_PULL_SIGNATURE"; or return 0
+
+        set -l did_change 0
+        for line in $filtered
+            set -l parts (string split -m 1 = -- "$line")
+            set -l key $parts[1]
+            _cmux_tmux_sync_key_is_managed "$key"; or continue
+            set -l value $parts[2]
+            if test "$$key" != "$value"
+                set -gx $key "$value"
+                set did_change 1
+            end
+        end
+
+        set -g _PROGRAMA_TMUX_PULL_SIGNATURE "$joined"
+        if test "$did_change" = 1
+            set -g _PROGRAMA_TTY_REPORTED 0
+            set -g _PROGRAMA_SHELL_ACTIVITY_LAST ""
+        end
+    end
+
+    function _cmux_tmux_sync_cmux_environment
+        if test -n "$TMUX"
+            _cmux_tmux_refresh_cmux_environment
+        else
+            _cmux_tmux_publish_cmux_environment
+        end
+    end
+
+    function _cmux_preexec --on-event fish_preexec
+        _cmux_tmux_sync_cmux_environment
+        _cmux_report_tty_once
+        _cmux_report_shell_activity_state running
+        _cmux_ports_kick command
+    end
+
+    function _cmux_prompt --on-event fish_prompt
+        _cmux_reset_terminal_keyboard_protocols
+        _cmux_tmux_sync_cmux_environment
+        _cmux_report_tty_once
+        _cmux_report_shell_activity_state prompt
+        set -l now (_cmux_now)
+        if test (math "$now - $_PROGRAMA_PORTS_LAST_RUN") -ge 5
+            _cmux_ports_kick refresh
+        end
+    end
+end
+
+# --- User config chain-load -------------------------------------------------
+# Our bootstrap points fish at this file via `--init-command 'source ...'` on a
+# plain `fish -il` invocation, so fish's own normal login-shell startup already
+# ran the user's real ~/.config/fish/config.fish, functions/, completions/, and
+# conf.d/*.fish *before* this file was sourced (Swift sets
+# PROGRAMA_FISH_USER_CONFIG_ALREADY_LOADED=1 for that path — see
+# GhosttyTerminalView.swift). This block only fires when that flag is absent,
+# e.g. a future remote-relay bootstrap that overrides HOME/XDG_CONFIG_HOME
+# before fish's normal startup can find the real user config.
+set -l _cmux_user_config_home ""
+if set -q PROGRAMA_FISH_CONFIG_HOME
+    set _cmux_user_config_home "$PROGRAMA_FISH_CONFIG_HOME"
+else if set -q HOME
+    set _cmux_user_config_home "$HOME/.config"
+end
+
+set -l _cmux_user_config "$_cmux_user_config_home/fish/config.fish"
+if not set -q PROGRAMA_FISH_USER_CONFIG_ALREADY_LOADED; and test -n "$_cmux_user_config_home"; and test "$_cmux_user_config_home" != "$XDG_CONFIG_HOME"
+    set -gx XDG_CONFIG_HOME "$_cmux_user_config_home"
+
+    set -l _cmux_user_functions "$_cmux_user_config_home/fish/functions"
+    if test -d "$_cmux_user_functions"; and not contains -- "$_cmux_user_functions" $fish_function_path
+        set -g fish_function_path "$_cmux_user_functions" $fish_function_path
+    end
+
+    set -l _cmux_user_completions "$_cmux_user_config_home/fish/completions"
+    if test -d "$_cmux_user_completions"; and not contains -- "$_cmux_user_completions" $fish_complete_path
+        set -g fish_complete_path "$_cmux_user_completions" $fish_complete_path
+    end
+
+    for _cmux_user_conf in "$_cmux_user_config_home"/fish/conf.d/*.fish
+        if test -r "$_cmux_user_conf"
+            source "$_cmux_user_conf"
+        end
+    end
+
+    if test -r "$_cmux_user_config"
+        source "$_cmux_user_config"
+    end
+end
diff --git a/Sources/GhosttyTerminalView.swift b/Sources/GhosttyTerminalView.swift
index d46ad68c..201e11dd 100644
--- a/Sources/GhosttyTerminalView.swift
+++ b/Sources/GhosttyTerminalView.swift
@@ -3456,6 +3456,34 @@ final class TerminalSurface: Identifiable, ObservableObject {
         return merged
     }
 
+    static func applyManagedFishStartupEnvironment(
+        integrationDir: String,
+        to environment: inout [String: String],
+        protectedKeys: inout Set<String>
+    ) {
+        let normalizedIntegrationDir = URL(fileURLWithPath: integrationDir, isDirectory: true)
+            .standardizedFileURL
+            .path
+        let integrationFile = URL(fileURLWithPath: normalizedIntegrationDir, isDirectory: true)
+            .appendingPathComponent("fish/config.fish")
+            .path
+
+        environment["PROGRAMA_FISH_INTEGRATION_FILE"] = integrationFile
+        environment["PROGRAMA_FISH_USER_CONFIG_ALREADY_LOADED"] = "1"
+        protectedKeys.insert("PROGRAMA_FISH_INTEGRATION_FILE")
+        protectedKeys.insert("PROGRAMA_FISH_USER_CONFIG_ALREADY_LOADED")
+    }
+
+    static func managedFishShellCommand(shell: String) -> String {
+        let initCommand = #"source "$PROGRAMA_FISH_INTEGRATION_FILE""#
+        return "\(shellSingleQuoted(shell)) -il --init-command \(shellSingleQuoted(initCommand))"
+    }
+
+    private static func shellSingleQuoted(_ value: String) -> String {
+        let escaped = value.replacingOccurrences(of: "'", with: "'\\''")
+        return "'\(escaped)'"
+    }
+
     func isAttached(to view: GhosttyNSView) -> Bool {
         attachedView === view && surface != nil
     }
@@ -3941,7 +3969,7 @@ final class TerminalSurface: Identifiable, ObservableObject {
 
         let scaleFactors = scaleFactors(for: view)
 
-        let baseConfig = configTemplate ?? ProgramaSurfaceConfigTemplate()
+        var baseConfig = configTemplate ?? ProgramaSurfaceConfigTemplate()
         var surfaceConfig = ghostty_surface_config_new()
         surfaceConfig.font_size = baseConfig.fontSize
         surfaceConfig.wait_after_command = baseConfig.waitAfterCommand
@@ -4090,6 +4118,15 @@ final class TerminalSurface: Identifiable, ObservableObject {
                         setManagedEnvironmentValue("PROMPT_COMMAND", bootstrap)
                     }
                 }
+            } else if shellName == "fish" {
+                Self.applyManagedFishStartupEnvironment(
+                    integrationDir: integrationDir,
+                    to: &env,
+                    protectedKeys: &protectedStartupEnvironmentKeys
+                )
+                if baseConfig.command?.isEmpty != false {
+                    baseConfig.command = Self.managedFishShellCommand(shell: shell)
+                }
             }
         }
         env = Self.mergedStartupEnvironment(
diff --git a/programaTests/GhosttyConfigTests.swift b/programaTests/GhosttyConfigTests.swift
index 05d528d4..4ee851d3 100644
--- a/programaTests/GhosttyConfigTests.swift
+++ b/programaTests/GhosttyConfigTests.swift
@@ -3956,6 +3956,274 @@ final class ZshShellIntegrationHandoffTests: XCTestCase {
     }
 }
 
+final class FishShellIntegrationHandoffTests: XCTestCase {
+    func testFishReportTtyPayloadIncludesSurfaceIdWithoutTmux() throws {
+        let output = try runInteractiveFish(
+            command: """
+            set -g _PROGRAMA_TTY_NAME ttys999
+            _cmux_report_tty_payload
+            """,
+            extraEnvironment: [
+                "PROGRAMA_TAB_ID": "11111111-1111-1111-1111-111111111111",
+                "PROGRAMA_PANEL_ID": "99999999-9999-9999-9999-999999999999",
+            ]
+        )
+
+        XCTAssertEqual(
+            output,
+            #"{"id":1,"method":"surface.report_tty","params":{"workspace_id":"11111111-1111-1111-1111-111111111111","tty_name":"ttys999","surface_id":"99999999-9999-9999-9999-999999999999"}}"#
+        )
+    }
+
+    func testFishReportTtyPayloadOmitsSurfaceIdWithTmux() throws {
+        let output = try runInteractiveFish(
+            command: """
+            set -g _PROGRAMA_TTY_NAME ttys555
+            _cmux_report_tty_payload
+            """,
+            extraEnvironment: [
+                "TMUX": "/tmp/tmux-current,123,0",
+                "PROGRAMA_WORKSPACE_ID": "11111111-1111-1111-1111-111111111111",
+                "PROGRAMA_TAB_ID": "11111111-1111-1111-1111-111111111111",
+                "PROGRAMA_PANEL_ID": "99999999-9999-9999-9999-999999999999",
+            ]
+        )
+
+        XCTAssertEqual(
+            output,
+            #"{"id":1,"method":"surface.report_tty","params":{"workspace_id":"11111111-1111-1111-1111-111111111111","tty_name":"ttys555"}}"#
+        )
+    }
+
+    func testFishRelayReportTtyUsesWorkspaceId() throws {
+        let fileManager = FileManager.default
+        let root = fileManager.temporaryDirectory
+            .appendingPathComponent("cmux-fish-relay-report-tty-\(UUID().uuidString)")
+        let binDir = root.appendingPathComponent("bin", isDirectory: true)
+        let logPath = root.appendingPathComponent("relay.log", isDirectory: false)
+
+        try fileManager.createDirectory(at: binDir, withIntermediateDirectories: true)
+        defer { try? fileManager.removeItem(at: root) }
+
+        try writeExecutableScript(
+            at: binDir.appendingPathComponent("programa", isDirectory: false),
+            contents: """
+            #!/bin/sh
+            printf '%s\\n' "$*" >> "\(logPath.path)"
+            exit 0
+            """
+        )
+
+        let output = try runInteractiveFish(
+            command: """
+            : > "\(logPath.path)"
+            set -g _PROGRAMA_TTY_NAME ttys777
+            _cmux_report_tty_via_relay
+            cat "\(logPath.path)"
+            """,
+            extraEnvironment: [
+                "PATH": "\(binDir.path):/usr/bin:/bin:/usr/sbin:/sbin",
+                "PROGRAMA_SOCKET_PATH": "127.0.0.1:64011",
+                "PROGRAMA_WORKSPACE_ID": "11111111-1111-1111-1111-111111111111",
+                "PROGRAMA_TAB_ID": "22222222-2222-2222-2222-222222222222",
+                "PROGRAMA_PANEL_ID": "22222222-2222-2222-2222-222222222222",
+            ]
+        )
+
+        XCTAssertTrue(
+            output.contains(#"rpc surface.report_tty {"workspace_id":"11111111-1111-1111-1111-111111111111","tty_name":"ttys777","surface_id":"22222222-2222-2222-2222-222222222222"}"#),
+            output
+        )
+    }
+
+    func testFishRelayPortsKickOmitsSurfaceIdUntilAvailable() throws {
+        let fileManager = FileManager.default
+        let root = fileManager.temporaryDirectory
+            .appendingPathComponent("cmux-fish-relay-kick-\(UUID().uuidString)")
+        let binDir = root.appendingPathComponent("bin", isDirectory: true)
+        let logPath = root.appendingPathComponent("relay.log", isDirectory: false)
+
+        try fileManager.createDirectory(at: binDir, withIntermediateDirectories: true)
+        defer { try? fileManager.removeItem(at: root) }
+
+        try writeExecutableScript(
+            at: binDir.appendingPathComponent("programa", isDirectory: false),
+            contents: """
+            #!/bin/sh
+            printf '%s\\n' "$*" >> "\(logPath.path)"
+            exit 0
+            """
+        )
+
+        let output = try runInteractiveFish(
+            command: """
+            : > "\(logPath.path)"
+            _cmux_ports_kick_via_relay refresh
+            for _cmux_i in (seq 1 20)
+                test -s "\(logPath.path)"; and break
+                sleep 0.05
+            end
+            cat "\(logPath.path)"
+            """,
+            extraEnvironment: [
+                "PATH": "\(binDir.path):/usr/bin:/bin:/usr/sbin:/sbin",
+                "PROGRAMA_SOCKET_PATH": "127.0.0.1:64011",
+                "PROGRAMA_WORKSPACE_ID": "11111111-1111-1111-1111-111111111111",
+                "PROGRAMA_TAB_ID": "22222222-2222-2222-2222-222222222222",
+            ]
+        )
+
+        XCTAssertTrue(
+            output.contains(#"rpc surface.ports_kick {"workspace_id":"11111111-1111-1111-1111-111111111111","reason":"refresh"}"#),
+            output
+        )
+        XCTAssertFalse(output.contains("surface_id"), output)
+    }
+
+    func testFishTmuxSyncPublishesOnlyWorkspaceScopedProgramaEnvironment() throws {
+        let fileManager = FileManager.default
+        let root = fileManager.temporaryDirectory
+            .appendingPathComponent("cmux-fish-tmux-publish-\(UUID().uuidString)")
+        let binDir = root.appendingPathComponent("bin", isDirectory: true)
+        let logPath = root.appendingPathComponent("tmux.log", isDirectory: false)
+
+        try fileManager.createDirectory(at: binDir, withIntermediateDirectories: true)
+        defer { try? fileManager.removeItem(at: root) }
+
+        try writeExecutableScript(
+            at: binDir.appendingPathComponent("tmux", isDirectory: false),
+            contents: """
+            #!/bin/sh
+            if [ "$1" = "show-environment" ] && [ "$2" = "-g" ]; then
+              exit 0
+            fi
+            printf '%s\\n' "$*" >> "\(logPath.path)"
+            exit 0
+            """
+        )
+
+        let output = try runInteractiveFish(
+            command: """
+            _cmux_tmux_sync_cmux_environment
+            cat "\(logPath.path)"
+            """,
+            extraEnvironment: [
+                "PATH": "\(binDir.path):/usr/bin:/bin:/usr/sbin:/sbin",
+                "PROGRAMA_SOCKET_PATH": "/tmp/programa-current.sock",
+                "PROGRAMA_TAG": "feat-fish-shell-integration",
+                "PROGRAMA_WORKSPACE_ID": "11111111-1111-1111-1111-111111111111",
+                "PROGRAMA_SURFACE_ID": "22222222-2222-2222-2222-222222222222",
+                "PROGRAMA_TAB_ID": "11111111-1111-1111-1111-111111111111",
+                "PROGRAMA_PANEL_ID": "22222222-2222-2222-2222-222222222222",
+            ]
+        )
+
+        XCTAssertTrue(output.contains("set-environment -g PROGRAMA_TAG feat-fish-shell-integration"), output)
+        XCTAssertTrue(output.contains("set-environment -g PROGRAMA_SOCKET_PATH /tmp/programa-current.sock"), output)
+        XCTAssertTrue(output.contains("set-environment -g PROGRAMA_WORKSPACE_ID 11111111-1111-1111-1111-111111111111"), output)
+        XCTAssertTrue(output.contains("set-environment -gu PROGRAMA_SURFACE_ID"), output)
+        XCTAssertTrue(output.contains("set-environment -gu PROGRAMA_PANEL_ID"), output)
+        XCTAssertFalse(output.contains("set-environment -g PROGRAMA_SURFACE_ID"), output)
+        XCTAssertFalse(output.contains("set-environment -g PROGRAMA_PANEL_ID"), output)
+    }
+
+    func testFishResetTerminalKeyboardProtocolsPrintsSequenceWhenForced() throws {
+        let output = try runInteractiveFish(
+            command: "_cmux_reset_terminal_keyboard_protocols",
+            extraEnvironment: [
+                "PROGRAMA_TEST_FORCE_KEYBOARD_RESET": "1",
+            ]
+        )
+
+        XCTAssertEqual(output, "\u{1B}[>m\u{1B}[<8u")
+    }
+
+    private func resolveFishExecutablePath() -> String? {
+        let candidates = [
+            "/opt/homebrew/bin/fish",
+            "/usr/local/bin/fish",
+            "/usr/bin/fish",
+            "/bin/fish",
+        ]
+        for candidate in candidates where FileManager.default.isExecutableFile(atPath: candidate) {
+            return candidate
+        }
+        return nil
+    }
+
+    private func requireFishExecutablePath() throws -> String {
+        guard let path = resolveFishExecutablePath() else {
+            throw XCTSkip("fish is not installed on this host")
+        }
+        return path
+    }
+
+    private func runInteractiveFish(
+        command: String,
+        extraEnvironment: [String: String] = [:]
+    ) throws -> String {
+        let fishPath = try requireFishExecutablePath()
+
+        let fileManager = FileManager.default
+        let root = fileManager.temporaryDirectory
+            .appendingPathComponent("cmux-fish-shell-integration-\(UUID().uuidString)")
+        try fileManager.createDirectory(at: root, withIntermediateDirectories: true)
+        defer { try? fileManager.removeItem(at: root) }
+
+        let repoRoot = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+        let integrationPath = repoRoot.appendingPathComponent("Resources/shell-integration/fish/config.fish")
+
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: fishPath)
+        process.arguments = [
+            "--no-config",
+            "--init-command", "source \"\(integrationPath.path)\"",
+            "-c", command,
+        ]
+        process.environment = [
+            "HOME": root.path,
+            "TERM": "xterm-256color",
+            "SHELL": fishPath,
+            "USER": NSUserName(),
+            "PATH": "/usr/bin:/bin:/usr/sbin:/sbin",
+            "PROGRAMA_FISH_USER_CONFIG_ALREADY_LOADED": "1",
+            "PROGRAMA_SHELL_INTEGRATION": "1",
+        ]
+        for (key, value) in extraEnvironment {
+            process.environment?[key] = value
+        }
+
+        let stdout = Pipe()
+        let stderr = Pipe()
+        process.standardOutput = stdout
+        process.standardError = stderr
+
+        try process.run()
+        let deadline = Date().addingTimeInterval(5)
+        while process.isRunning && Date() < deadline {
+            _ = RunLoop.current.run(mode: .default, before: Date().addingTimeInterval(0.01))
+        }
+        if process.isRunning {
+            process.terminate()
+            process.waitUntilExit()
+            XCTFail("Timed out waiting for fish to exit")
+        }
+
+        let output = String(data: stdout.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? ""
+        let error = String(data: stderr.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? ""
+
+        XCTAssertEqual(process.terminationStatus, 0, error)
+        return output.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    private func writeExecutableScript(at url: URL, contents: String) throws {
+        try contents.write(to: url, atomically: true, encoding: .utf8)
+        try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: url.path)
+    }
+}
+
 final class BrowserInstallDetectorTests: XCTestCase {
     func testDetectInstalledBrowsersUsesBundleIdAndProfileData() throws {
         let home = makeTemporaryHome()