# Otty zsh integration — payload (sourced from ~/.zshrc managed block)
#
# Idempotent: re-sourcing in the same shell is a no-op. `__otty_loaded` is a
# plain (non-exported) parameter, so each fresh shell process re-installs the
# hooks while a second source within one shell is skipped.
[[ -n "$__otty_loaded" ]] && return
__otty_loaded=1

# ── Bundled `otty` on PATH ──
# Otty ships a CLI binary inside the .app bundle. If "Install CLI" has not
# been run (no /usr/local/bin/otty symlink), point shells at our per-process
# bin dir so `otty …` still works without polluting the user's system. Done
# at the end of .zshrc so we win any PATH-setting they do; the case guard
# avoids appending the same dir twice across nested shells.
if [[ -n "$OTTY_BIN_DIR" && -d "$OTTY_BIN_DIR" ]]; then
    case ":$PATH:" in
        *":$OTTY_BIN_DIR:"*) ;;
        *) export PATH="$OTTY_BIN_DIR:$PATH" ;;
    esac
fi

# ── OSC 133 FTCS markers ──
__otty_cmd_executed=""
__otty_progress_active=""

# Match command line against $OTTY_PROGRESS_COMMANDS (pipe-separated list of
# whitespace-delimited prefixes, e.g. "git push").
__otty_progress_match() {
    emulate -L zsh
    setopt sh_word_split
    local cmd="$1"
    [[ -z "$OTTY_PROGRESS_COMMANDS" ]] && return 1
    # Strip leading `NAME=value` env assignments (must be followed by a space).
    while [[ "$cmd" == [A-Za-z_]*=*' '* ]]; do
        local first="${cmd%% *}"
        [[ "$first" == *=* ]] || break
        cmd="${cmd#* }"
    done
    local IFS='|'
    local p
    for p in $OTTY_PROGRESS_COMMANDS; do
        [[ -z "$p" ]] && continue
        if [[ "$cmd" == "$p" || "$cmd" == "$p "* ]]; then
            return 0
        fi
    done
    return 1
}

__otty_precmd() {
    local ret=$?
    if [[ -n "$__otty_cmd_executed" ]]; then
        builtin printf '\e]133;D;%d\a' "$ret"
    fi
    if [[ -n "$__otty_progress_active" ]]; then
        if (( ret == 0 )); then
            builtin printf '\e]9;4;5;0\a'
        else
            builtin printf '\e]9;4;2\a'
        fi
        __otty_progress_active=""
    fi
    # Stamp our per-session token on the prompt mark. OSC 133 is a public
    # convention — programs running under us emit ;A for their own output —
    # so this is what lets the terminal tell OUR prompt from theirs. Falls
    # back to a bare mark when no token was handed to us.
    # Not inside a multiplexer only. A nested shell inherits the very same
    # token, and a multiplexer can forward marks to the outer terminal — today
    # by a script wrapping them in tmux's DCS passthrough, and possibly by
    # default in future (tmux/tmux#5237). An inner prompt would then
    # authenticate against the OUTER terminal and reclaim state belonging to
    # the multiplexer itself, yanking it off the alternate screen mid-session.
    # Dropping the token degrades to a bare mark: nothing is reclaimed, which
    # is what terminals without this feature do anyway.
    if [[ -n "$OTTY_PROMPT_TOKEN" && -z "$TMUX" && -z "$STY" && -z "$ZELLIJ" ]]; then
        builtin printf '\e]133;A;otty=%s\a' "$OTTY_PROMPT_TOKEN"
    else
        builtin printf '\e]133;A\a'
    fi
    __otty_cmd_executed=""
}
__otty_preexec() {
    builtin printf '\e]133;C\a'
    __otty_cmd_executed=1
    if __otty_progress_match "$1"; then
        builtin printf '\e]9;4;3\a'
        __otty_progress_active=1
    fi
}
precmd_functions+=(__otty_precmd)
preexec_functions+=(__otty_preexec)

# ── OSC 7 reporting ──
# Every OSC 7 goes through here. Both guards are load-bearing and neither
# subsumes the other; see scripts/test-shell-integration.sh for the matrix.
#
# ZSH_SUBSHELL — chpwd hooks also run in FORKED subshells, and a command
# substitution is a forked subshell whose stdout is the pipe the parent reads
# back as a value. So `r=$(cd sub && pwd)` captured this escape into $r,
# yielding a string that prints identically to the right path but fails every
# file test. Only code sourced into the interactive shell hit it; a script runs
# in a child with no hooks installed, which is why it looked terminal-specific.
# Suppressing is also the semantically correct answer rather than a workaround:
# a `cd` inside `$( )`, `( … )`, a pipeline segment or a background job never
# moves the interactive shell, so there is no new directory to report. That
# case can still have a tty on stdout, so -t alone would let it through.
#
# -t 1 — a chpwd hook runs INSIDE the triggering command's redirections, so
# `cd sub > out` writes the escape into out. That emission never reached the
# terminal to begin with (the redirect swallowed it), so gating on it forfeits
# no reporting we actually have today, and it stops the file corruption.
# Routing to /dev/tty instead would recover those, but a failed `>/dev/tty`
# prints "device not configured" regardless of where 2>/dev/null is placed —
# not a trade worth making in a file every interactive shell sources.
__otty_osc7() {
    (( ZSH_SUBSHELL == 0 )) && [[ -t 1 ]] || return 0
    builtin printf '\e]7;%s\a' "$1"
}

# CWD reporting (fires on every directory change).
__otty_chpwd() {
    __otty_osc7 "file://${HOST}${PWD}"
}
chpwd_functions+=(__otty_chpwd)
# Emit initial CWD so the sidebar knows the starting directory.
__otty_chpwd

# ── Omit `otty` prefix (live-toggleable) ──
# Install `edit`/`view`/`watch`/`jump`/`learn` wrappers ONCE; each one stat()s the
# omit_prefix sentinel under $OTTY_FLAGS_DIR at call time so the Settings
# toggle takes effect immediately, without waiting for the next precmd
# cycle. Sentinel absent → fall through to `command <name>` so PATH lookup
# behaves exactly as if the wrapper weren't there (system `watch` on Linux
# still works). By default, names already defined as user functions/aliases
# are left untouched; the `allow_overwrite` sentinel (evaluated at shell
# init — restart the shell for the toggle to take effect) opts into
# replacing them.
__otty_should_wrap() {
    if [[ -n "$OTTY_FLAGS_DIR" && -f "$OTTY_FLAGS_DIR/allow_overwrite" ]]; then
        # Overwrite mode: our wrapper wins. An alias outranks a function at
        # command lookup, so a conflicting one has to go or it would shadow the
        # wrapper we are about to install.
        (( ${+aliases[$1]} )) && unalias "$1"
        return 0
    fi
    # Preserve mode: leave any pre-existing user binding untouched, skip ours.
    (( ${+functions[$1]} || ${+aliases[$1]} )) && return 1
    return 0
}

# The wrappers below use the `function NAME { … }` keyword form, NOT the
# `NAME() { … }` form. Aliases are expanded at PARSE time, so for a user with
# e.g. `alias view='vim -R'` in an rc file sourced ahead of us, the parser
# rewrites `view()` into `vim -R()` and the whole script dies on a syntax error
# — taking OSC markers, CWD reporting and SSH integration down with it. The
# `__otty_should_wrap view &&` guard on the same line cannot save us: the entire
# `A && B` list is parsed before any of it runs. The keyword form suppresses
# alias expansion of the name, so the definition parses no matter what the user
# has aliased. Don't "simplify" it back to `view() {`.
__otty_should_wrap edit && function edit {
    if [[ -n "$OTTY_FLAGS_DIR" && -f "$OTTY_FLAGS_DIR/omit_prefix" ]]; then
        command otty edit "$@"
    else
        command edit "$@"
    fi
}
__otty_should_wrap view && function view {
    if [[ -n "$OTTY_FLAGS_DIR" && -f "$OTTY_FLAGS_DIR/omit_prefix" ]]; then
        command otty view "$@"
    else
        command view "$@"
    fi
}
__otty_should_wrap watch && function watch {
    if [[ -n "$OTTY_FLAGS_DIR" && -f "$OTTY_FLAGS_DIR/omit_prefix" ]]; then
        command otty watch "$@"
    else
        command watch "$@"
    fi
}
__otty_should_wrap jump && function jump {
    if [[ -n "$OTTY_FLAGS_DIR" && -f "$OTTY_FLAGS_DIR/omit_prefix" ]]; then
        # Zoxide-style: ask the app to resolve only (no `cd` injection into
        # the focused pane) and `builtin cd` locally — keeps the transcript
        # silent (no echoed `cd '<path>'` from line-discipline, no duplicate
        # prompt after CLI exits).
        if (( $# == 0 )); then
            # No-args: toggle between $HOME and the last jump-source dir.
            # Local-only state ($OTTY_JUMP_PREV) so up-arrow still recalls
            # the user's literal `jump` invocation, not an injected `cd`.
            if [[ "$PWD" == "$HOME" && -n "$OTTY_JUMP_PREV" ]]; then
                local _otty_dest="$OTTY_JUMP_PREV"
                OTTY_JUMP_PREV="$PWD"
                builtin cd -- "$_otty_dest"
            else
                OTTY_JUMP_PREV="$PWD"
                builtin cd -- "$HOME"
            fi
            return
        fi
        local _otty_p
        _otty_p=$(command otty jump --no-cd "$@") || return
        if [[ -n "$_otty_p" ]]; then
            OTTY_JUMP_PREV="$PWD"
            builtin cd -- "$_otty_p"
        fi
    else
        command jump "$@"
    fi
}
__otty_should_wrap learn && function learn {
    if [[ -n "$OTTY_FLAGS_DIR" && -f "$OTTY_FLAGS_DIR/omit_prefix" ]]; then
        command otty learn "$@"
    else
        command learn "$@"
    fi
}
# `watch:<agent>` — wait for a Claude/Codex/OpenCode session to reach
# idle. The colon is part of the command name as far as the shell is
# concerned, so the bare `watch` wrapper above never catches it; install
# one wrapper per agent. Keep in sync with WATCH_AGENTS in cli/src/main.rs.
for __otty_a in claude codex opencode; do
    __otty_should_wrap "watch:$__otty_a" && eval "watch:$__otty_a() {
        if [[ -n \"\$OTTY_FLAGS_DIR\" && -f \"\$OTTY_FLAGS_DIR/omit_prefix\" ]]; then
            command otty watch:$__otty_a \"\$@\"
        else
            command watch:$__otty_a \"\$@\"
        fi
    }"
done
unset __otty_a

# ── Custom CLI aliases ($OTTY_CLI_ALIASES = "name=cmd|name=cmd|…") ──
# Define `name() { command otty <cmd> "$@" }` for each pair the bridge passed
# in. The `allow_overwrite` sentinel still gates whether we replace names the
# user has already defined.
if [[ -n "$OTTY_CLI_ALIASES" ]]; then
    () {
        emulate -L zsh
        setopt sh_word_split
        local IFS='|'
        local pair name cmd
        for pair in $OTTY_CLI_ALIASES; do
            [[ -z "$pair" ]] && continue
            name="${pair%%=*}"
            cmd="${pair#*=}"
            [[ -z "$name" || -z "$cmd" || "$name" == "$pair" ]] && continue
            # Validate identifier and command. `=~` uses POSIX ERE in both
            # bash and zsh and is unaffected by KSH_GLOB / EXTENDED_GLOB,
            # both of which `emulate -L zsh` turns off — using `==` with a
            # ksh-style `*(...)` pattern here would silently reject every
            # alias under emulate.
            [[ "$name" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
            [[ "$cmd"  =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
            __otty_should_wrap "$name" || continue
            # When the alias maps to a wrapped command (jump/edit/view/watch/
            # learn), delegate to that wrapper so its `--no-cd`/builtin-cd
            # logic still runs. Calling `command otty $cmd` directly would
            # bypass the wrapper and re-introduce the visible `cd '<path>'`
            # echo + spurious shell-history entry that the wrapper exists
            # to suppress.
            case "$cmd" in
                jump|edit|view|watch|learn)
                    functions[$name]="$cmd \"\$@\""
                    ;;
                *)
                    functions[$name]="command otty $cmd \"\$@\""
                    ;;
            esac
        done
    }
fi

unfunction __otty_should_wrap

# Dump aliases + the resolved interactive $PATH to temp files so the
# autocomplete engine can read them without spawning a shell. The app
# process only inherits the bare launchd PATH (/usr/bin:/bin:…) when
# launched from Finder, so command-name completion relies on this dump to
# discover Homebrew/cargo/mise/etc. binaries on the user's real PATH.
__otty_dump_aliases() {
    # Use >| (explicit clobber) so these internal cache writes succeed even
    # when the user has `setopt noclobber`; the per-uid filenames are fixed,
    # so a plain > redirection errors with "file exists" on every new shell.
    builtin alias >| "${TMPDIR:-/tmp}/otty-aliases-${EUID}" 2>/dev/null
    print -rn -- "$PATH" >| "${TMPDIR:-/tmp}/otty-path-${EUID}" 2>/dev/null
    precmd_functions=("${(@)precmd_functions:#__otty_dump_aliases}")
}
precmd_functions+=(__otty_dump_aliases)

# Emit B mark (command-input-start) after each prompt via zle.
if [[ -o interactive ]] 2>/dev/null; then
    # Capture the existing widget's backing function (if any),
    # but skip if it's already ours (avoid infinite recursion).
    __otty_orig_line_init_fn=""
    if [[ "${widgets[zle-line-init]}" == user:* ]]; then
        local orig_fn="${widgets[zle-line-init]#user:}"
        if [[ "$orig_fn" != __otty_zle_line_init ]]; then
            __otty_orig_line_init_fn="$orig_fn"
        fi
    fi

    __otty_zle_line_init() {
        builtin printf '\e]133;B\a'
        # Call the original function directly (not via zle) to
        # avoid re-entering our own widget.
        if [[ -n "$__otty_orig_line_init_fn" ]] && (( ${+functions[$__otty_orig_line_init_fn]} )); then
            "$__otty_orig_line_init_fn"
        fi
    }
    builtin zle -N zle-line-init __otty_zle_line_init
fi

# ── Shift+Enter → insert newline ──
# Otty encodes Shift+Enter as CSI u (`ESC [ 13 ; 2 u`) so agent TUIs (Claude
# Code, codex, …) can tell it apart from plain Enter — they read the sequence
# straight from stdin without enabling any keyboard protocol, so the encoder
# emits it even in legacy mode (same convention as kitty/Ghostty). zle doesn't
# speak CSI u: unbound, the unmatched tail self-inserts as literal `;2u`.
# Bind it to a real newline insert instead — zle edits multi-line buffers
# natively, so Shift+Enter composes multi-line commands at the prompt.
# NOT self-insert-unmeta: that inserts the sequence's LAST key (`u`).
if [[ -o interactive ]] 2>/dev/null; then
    __otty_insert_newline() { LBUFFER+=$'\n' }
    builtin zle -N __otty_insert_newline
    bindkey '\e[13;2u' __otty_insert_newline
fi

# ── Command history scope ($OTTY_HISTORY_SCOPE) ──
# We run from the first precmd, i.e. AFTER the user's .zshrc and any plugin
# manager, so this wins over oh-my-zsh's `setopt share_history` — the reason
# arrowing up in one tab otherwise surfaces a sibling tab's commands.
#
# Only the WHEN of reading/writing changes, never the history file's contents:
# every mode still reads the whole file at startup, so a fresh pane always
# inherits the full history. `per-pane` merely stops it from picking up what
# other panes write while it is alive. An unset variable means "follow the
# user's own configuration" and touches nothing.
case "${OTTY_HISTORY_SCOPE:-}" in
    shared)
        setopt share_history
        ;;
    per-pane)
        unsetopt share_history
        # Still append each command as it runs, so the NEXT pane to open
        # inherits it. Without this the history is only flushed at exit and a
        # crashed shell loses the session.
        setopt inc_append_history
        ;;
esac

# ── Up/Down arrow behavior ($OTTY_HISTORY_UP_ARROW) ──
# `up-line-or-beginning-search` moves within a multi-line buffer first and only
# reaches for history from the first line — the reason we prefer it over
# `history-beginning-search-backward`. Both the normal (`\e[A`) and application
# mode (`\eOA`) encodings must be bound: zsh switches to the latter via smkx.
if [[ -o interactive ]] 2>/dev/null; then
    case "${OTTY_HISTORY_UP_ARROW:-}" in
        prefix-search)
            builtin autoload -Uz up-line-or-beginning-search down-line-or-beginning-search
            builtin zle -N up-line-or-beginning-search
            builtin zle -N down-line-or-beginning-search
            bindkey '\e[A' up-line-or-beginning-search
            bindkey '\eOA' up-line-or-beginning-search
            bindkey '\e[B' down-line-or-beginning-search
            bindkey '\eOB' down-line-or-beginning-search
            ;;
        sequential)
            bindkey '\e[A' up-line-or-history
            bindkey '\eOA' up-line-or-history
            bindkey '\e[B' down-line-or-history
            bindkey '\eOB' down-line-or-history
            ;;
    esac
fi

# ── Restored pane: load this pane's own history ($OTTY_PANE_HISTORY) ──
# Set only for a pane Otty is restoring; a freshly created pane never sees it.
#
# `fc -R` appends the entries to this session's history list, so they land
# NEWER than everything zsh already read from the real history file: Up reaches
# what THIS pane ran before the restart, and keeps going into the global
# history behind it. zsh treats them as already-on-disk, so they are never
# written back — the user's real history file is not touched, and repeated
# restarts cannot accumulate copies.
#
# Why not point HISTFILE at the file instead: on macOS `/etc/zshrc` assigns
# HISTFILE unconditionally, after our .zshenv and before the user's .zshrc, so
# steering the read that way is not possible.
#
# WHEN this runs decides everything, because zsh reads HISTFILE only after the
# whole startup chain — so a `fc -R` from inside .zshrc lands the entries
# BEFORE the global history rather than after it, and Up hits whatever a
# sibling pane wrote last (hundreds of presses from this pane's own commands,
# not "a few"). The payload has two load points and only one of them is late
# enough:
#
#   * from our .zshenv's first-precmd loader — HISTFILE is already read, so
#     reading here is correct and must happen NOW: a function appended to
#     precmd_functions while zsh is iterating that array runs on the NEXT
#     prompt, one prompt too late for the first Up.
#   * from the managed .zshrc block (the tmux fallback, dev builds without a
#     bundle — and, since the block is installed whenever tmux exists, the
#     ORDINARY path on any machine with tmux) — HISTFILE has not been read
#     yet, so defer to the first precmd.
#
# `__otty_precmd_load` is set by the .zshenv loader across its `source`, and is
# the only thing that tells the two apart.
if [[ -o interactive ]] 2>/dev/null \
   && [[ -n "$OTTY_PANE_HISTORY" && -r "$OTTY_PANE_HISTORY" ]]; then
    __otty_load_pane_history() {
        # Re-check: under the deferred path a nested shell may have consumed
        # (and unset) the variable between load and first prompt.
        if [[ -n "$OTTY_PANE_HISTORY" && -r "$OTTY_PANE_HISTORY" ]]; then
            fc -R "$OTTY_PANE_HISTORY" 2>/dev/null
        fi
        # Strictly one-shot. The variable is exported, so a nested interactive
        # zsh (or one started by a script in this pane) would inherit it and
        # load the same entries a second time into its own list.
        builtin unset OTTY_PANE_HISTORY
        precmd_functions=("${(@)precmd_functions:#__otty_load_pane_history}")
    }
    if [[ -n "$__otty_precmd_load" ]]; then
        __otty_load_pane_history
    else
        precmd_functions+=(__otty_load_pane_history)
    fi
fi

# ── SSH Integration ──
if [[ "${OTTY_SSH_INTEGRATION:-}" == "1" ]]; then
    ssh() {
        local _otty_term="xterm-256color"
        local -a _otty_opts=(
            -o "SetEnv=COLORTERM=truecolor TERM_PROGRAM=otty"
            -o "SendEnv=COLORTERM TERM_PROGRAM TERM_PROGRAM_VERSION"
        )

        # ── Resolve hostname via ssh -G ──
        local _otty_user="" _otty_hostname=""
        while IFS=' ' read -r _k _v; do
            case "$_k" in
                user) _otty_user="$_v" ;;
                hostname) _otty_hostname="$_v" ;;
            esac
            [[ -n "$_otty_user" && -n "$_otty_hostname" ]] && break
        done < <(command ssh -G "$@" 2>/dev/null)

        local _otty_target="${_otty_user}@${_otty_hostname}"
        local _otty_meta_file="${TMPDIR:-/tmp}/otty-ssh-shell-$$.meta"
        local _otty_ctl_path=""
        local _otty_ctl_dir=""

        # ── Split argv into connection args and the remote command ──
        # `ssh host cmd` folds every trailing argument into ONE remote command
        # string, so anything appended after the user's own arguments lands as
        # arguments OF their command. The terminfo probe below used to pass
        # "$@" and then append its script, which made the remote run
        #     <user command> otty_term=…; <probe script>
        # — the user's command executed a second time, in the probe connection,
        # with a stray argument glued on.
        #
        # Where the connection arguments end is a getopt(3) question — which
        # letters take a value, how clusters like `-vp 2222` split, that ssh
        # re-enters getopt after the destination — and it is answered in ONE
        # place, `otty ssh scan-argv` (packages/ssh-argv), which the macOS app
        # also reaches through the FFI. It used to be four transcriptions of
        # the same rules in four languages, and they drifted: OpenSSH 9.4's
        # `-P tag` took a value in none of them.
        #
        # `otty` is on PATH here — the payload prepends $OTTY_BIN_DIR at the
        # top of this file. When it is not (a hand-installed payload with no
        # app behind it), the safe degradation is the one already used for a
        # ControlPath we cannot mint: skip the extras and let plain ssh run.
        local -a _otty_conn=()
        local _otty_has_cmd=0 _otty_scan_ok=0
        local _otty_scan
        _otty_scan="$(command otty ssh scan-argv -- "$@" 2>/dev/null)"
        case "$_otty_scan" in
            conn=*\ cmd=*)
                local _otty_n="${_otty_scan#conn=}"
                _otty_n="${_otty_n%% *}"
                _otty_has_cmd="${_otty_scan##*cmd=}"
                # Positional parameters are 1-based in both shells, and a count
                # of 0 yields an empty array rather than an error.
                _otty_conn=("${@:1:$_otty_n}")
                _otty_scan_ok=1
                ;;
        esac

        # `_otty_scan_ok` too: without a scan we do not know where the
        # user's remote command begins, so neither the probe nor a
        # ControlMaster (whose teardown needs the same split) may run.
        if [[ -n "$_otty_hostname" ]] && (( _otty_scan_ok )); then
            # Set up a ControlMaster socket so the main connection can be reused
            # for SFTP/exec by the file/git panels.
            #
            # If the caller already passed an explicit ControlPath, honor it and
            # don't mint a competing master. Otty's split-pane "inherit SSH"
            # passes `-o ControlPath=<socket>` to ride the existing master — no
            # re-auth, no proxy/alias re-resolution.
            local _otty_arg
            for _otty_arg in "$@"; do
                case "$_otty_arg" in
                    ControlPath=*) _otty_ctl_path="${_otty_arg#ControlPath=}" ;;
                esac
            done
            if [[ -z "$_otty_ctl_path" ]]; then
                # ControlPath must stay short: macOS caps Unix-domain socket
                # paths at 104 bytes and $TMPDIR (/var/folders/...) already eats
                # ~49 of them, so the socket goes directly under /tmp instead.
                # mktemp -d yields a fresh 0700 dir, keeping this race-free.
                #
                # Deliberately no fallback when mktemp is unavailable. A
                # predictable name like /tmp/otty-ssh.$$ in a world-writable
                # directory can be pre-created by another local user, and this
                # path becomes the `-o ControlPath` that every panel exec and
                # SFTP transfer rides — the same class of attack the host guards
                # against when it vets the metadata file's ownership. Skipping
                # multiplexing is the safe degradation: socket= is written empty
                # and the host simply leaves controlSocket unset.
                _otty_ctl_dir="$(mktemp -d /tmp/otty-ssh.XXXXXX 2>/dev/null)"
                if [[ -n "$_otty_ctl_dir" ]]; then
                    _otty_ctl_path="$_otty_ctl_dir/socket"
                    _otty_opts+=(
                        -o "ControlMaster=auto"
                        -o "ControlPath=$_otty_ctl_path"
                        -o "ControlPersist=60"
                    )
                fi
            fi

            # Terminfo install (cached per user@host).
            #
            # Skipped entirely when the caller supplied a remote command: a
            # probe there would open a second connection behind the back of a
            # script that asked for exactly one, and terminfo only matters for a
            # session that has a tty. TERM then stays at the xterm-256color
            # default, which every system terminfo database already resolves.
            local _otty_cache_dir="${TMPDIR:-/tmp}/otty-terminfo-cache"
            command mkdir -p "$_otty_cache_dir" 2>/dev/null
            local _otty_cache_file="$_otty_cache_dir/$_otty_target"

            if [[ -f "$_otty_cache_file" ]]; then
                _otty_term="${TERM:-xterm-256color}"
            elif (( ! _otty_has_cmd )) && command -v infocmp >/dev/null 2>&1; then
                local _otty_terminfo
                _otty_terminfo="$(infocmp -0 -x 2>/dev/null)"

                if [[ -n "$_otty_terminfo" ]]; then
                    # Remote command (TERM injected via the leading assignment):
                    #   1. If the remote already resolves this TERM (system DB or
                    #      a user entry), do nothing — never shadow a standard
                    #      name like xterm-256color with our copy.
                    #   2. Otherwise install via `tic`, then verify the fresh
                    #      entry actually has `clear=`; a truncated transfer can
                    #      compile a stub that lacks clear/cup and breaks tput &
                    #      tmux. If incomplete, remove it and fail so we fall back
                    #      to the system database instead of a broken shadow.
                    # Deliberately NOT sharing $_otty_ctl_path here. This probe
                    # used to run with ControlMaster=yes and hand its master to
                    # the interactive ssh below, saving one auth round-trip. But
                    # that demoted the interactive connection to a mux *client*,
                    # and a client's interactive session can hang with no output
                    # at all — no banner, no prompt, nothing — which reads as
                    # "ssh froze". It only bit on the first connection to a host
                    # (later ones hit the terminfo cache and skipped this probe
                    # entirely), which is what made it look intermittent.
                    # ControlPath=none keeps the probe off the socket so the
                    # interactive ssh below stays the master.
                    if builtin printf '%s' "$_otty_terminfo" | command ssh \
                        -o "ControlMaster=no" \
                        -o "ControlPath=none" \
                        "${_otty_conn[@]}" \
                        "otty_term=${TERM:-xterm-256color}; "'command -v infocmp >/dev/null 2>&1 && infocmp "$otty_term" >/dev/null 2>&1 && exit 0; command -v tic >/dev/null 2>&1 || exit 1; mkdir -p ~/.terminfo 2>/dev/null; tic -x - >/dev/null 2>&1 || exit 1; command -v infocmp >/dev/null 2>&1 && { infocmp -1 "$otty_term" 2>/dev/null | grep -q "clear=" || { rm -f ~/.terminfo/?/"$otty_term" ~/.terminfo/??/"$otty_term" 2>/dev/null; exit 1; }; }; exit 0' \
                        2>/dev/null; then
                        _otty_term="${TERM:-xterm-256color}"
                        command touch "$_otty_cache_file"
                    elif [[ -n "${OTTY_DEBUG_SSH:-}" ]]; then
                        # Nothing is cached on failure — deliberately, so a host
                        # that later grows `tic` is picked up — which means a
                        # permanently failing probe re-runs on every connection.
                        # Opt-in only: an unconditional line here would land in
                        # the middle of `logs=$(ssh host …)`.
                        builtin print -ru2 -- "otty: terminfo probe failed for $_otty_target; TERM stays xterm-256color"
                    fi
                fi
            fi

            # Write metadata file so Otty's Swift side can find the resolved
            # session info (user, hostname, socket) even when ~/.ssh/config
            # aliases the user or hostname.
            {
                builtin print "user=${_otty_user}"
                builtin print "hostname=${_otty_hostname}"
                builtin print "socket=${_otty_ctl_path}"
            } > "$_otty_meta_file" 2>/dev/null
        fi

        # Notify Otty we're entering an SSH session. Same guarded path as
        # chpwd: `logs=$(ssh host cat …)` runs this whole wrapper in a
        # command-substitution subshell, and an unguarded write here wrapped
        # the captured output in OSC 7 exactly the way chpwd corrupted $( ).
        __otty_osc7 "ssh://${_otty_hostname:-unknown}"

        TERM="$_otty_term" command ssh "${_otty_opts[@]}" "$@"
        local _ret=$?

        command rm -f "$_otty_meta_file" 2>/dev/null

        # Retire the ControlMaster we minted above. Only ours — a ControlPath the
        # caller passed in belongs to whoever created it, hence the _otty_ctl_dir
        # guard. Without this the master lingers for the whole ControlPersist
        # window and its mktemp'd directory was never removed at all, so every
        # ssh invocation leaked one empty /tmp/otty-ssh.XXXXXX forever.
        if [[ -n "$_otty_ctl_dir" ]]; then
            command ssh -o "ControlPath=$_otty_ctl_path" -O exit "${_otty_conn[@]}" >/dev/null 2>&1
            command rm -rf "$_otty_ctl_dir" 2>/dev/null
        fi
        # Sweep dirs orphaned by earlier crashes. -empty means a live master's
        # dir (it still holds its socket) is never touched. The trailing slash on
        # /tmp/ is load-bearing: on macOS /tmp is a symlink to private/tmp and
        # find won't descend into it without one, silently matching nothing.
        command find /tmp/ -maxdepth 1 -type d -name 'otty-ssh.*' -empty -delete 2>/dev/null

        # Restore local CWD reporting. Guarded in lockstep with the ssh:// mark
        # above — both conditions are unchanged across the call, so the pair is
        # always emitted together or not at all.
        __otty_osc7 "file://${HOST}${PWD}"
        return $_ret
    }
fi
