terminal window change was not observed before the deadline

Error message

terminal window change was not observed before the deadline

What it means

toggle_pin's final wait_for polls (up to 400ms) for the window to reach the requested target state (position/size/topmost/maximized). If the loop exhausts without observing a match — and the restore path did not reset state — the function bails with this error, indicating the window change was requested but never confirmed.

Solutions

Retry toggle_pin — transient contention commonly causes deadline misses.
Close competing window-management utilities (or hotkeys) that reposition or unpin the terminal.
Re-capture the host and toggle again if the window's state was changed externally mid-operation.
If reproducible under load, increase the 400ms apply deadline in window_control.rs (toggle_pin).

Defensive patterns

Strategy: retry

Try / catch

match toggle_pin() {
    Err(e) if e.to_string().contains("not observed before the deadline") => retry_once_after_delay(),
    other => other?,
}

Prevention

Retry; 400ms is short on loaded systems.
Disable competing window managers/hotkey tools that move the same window.
Avoid toggling during monitor/DPI changes.
Fall back gracefully: if the state can't be confirmed, leave pinning off.

When it happens

Trigger: wait_for(host, 400ms, |observed| observed.matches(target)) returned false: SetWindowPos/ShowWindow were issued but observation never saw the window match the target state before the deadline (excluding the early-return path when the change was already observed).

Common situations: Heavy system load slowing window updates; another program (window manager, hotkey tool) fighting over the window's position/topmost flag; DPI/monitor changes invalidating the computed rect; the 400ms deadline being too tight.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/63e80a18a5fdba6e. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/tui/window_control.rs:476

                }
            }
            let applied = wait_for(host, Duration::from_millis(400), |observed| {
                observed.matches(target)
            })?;
            tracing::info!(
                applied,
                restoring,
                attempt,
                "window_control: observed window result"
            );
            if applied {
                if restoring {
                    *state = State::new();
                }
                return Ok(target.topmost);
            }
        }
        bail!("terminal window change was not observed before the deadline")
    }

    pub(super) fn pinned() -> bool {
        PINNED.load(Ordering::Acquire)
    }

    #[cfg(test)]
    mod tests {
        use super::*;

        #[test]
        fn pin_receipt_requires_observed_geometry_and_topmost_state() {
            let target = Observation {
                rect: RECT {
                    left: 20,
                    top: 30,
                    right: 660,
                    bottom: 430,

View on GitHub (pinned to 73e0f67d83)