herdrdev/herdr · warning · io::Error

direct terminal attach is not supported on Windows yet

Error message

direct terminal attach is not supported on Windows yet

What it means

On Windows, run_terminal_attach (src/client/mod.rs:953) is a stub that always returns io::ErrorKind::Unsupported: direct raw-byte terminal attach is intentionally Unix-only until Windows gets a semantic attach path. The debug_assert also documents that platform capabilities advertise this as unavailable.

Source

Thrown at src/client/mod.rs:953

    )
}

/// Runs a direct terminal attach client.
#[cfg(unix)]
pub fn run_terminal_attach(terminal_id: String, takeover: bool) -> io::Result<()> {
    run_client_with_mode(
        RenderEncoding::TerminalAnsi,
        Some((terminal_id, takeover)),
        Some(AttachEscapeState::default()),
        "attaching to terminal",
    )
}

/// Direct terminal attach is Unix raw-byte input only until Windows gets a semantic attach path.
#[cfg(windows)]
pub fn run_terminal_attach(_terminal_id: String, _takeover: bool) -> io::Result<()> {
    debug_assert!(!crate::platform::capabilities().direct_terminal_attach);
    Err(io::Error::new(
        io::ErrorKind::Unsupported,
        "direct terminal attach is not supported on Windows yet",
    ))
}

/// Runs a read-only terminal session observer and prints one JSON envelope per frame.
pub fn run_terminal_session_observe(target: String, cols: u16, rows: u16) -> io::Result<()> {
    let mut stream =
        connect_terminal_session_stream(target.clone(), cols, rows, "observing terminal session")?;
    write_to_server(&mut stream, &ClientMessage::ObserveTerminal { target })?;
    write_terminal_session_output(stream)
}

/// Runs a writable terminal session controller.
pub fn run_terminal_session_control(
    target: String,
    takeover: bool,
    cols: u16,

View on GitHub (pinned to f457cff4f2)

Solutions

1. Use the supported Windows path (semantic attach / client session stream) instead of direct attach
2. Gate scripts by platform: only call direct attach when the capability is advertised, not by OS guess
3. Track herdr releases for Windows direct attach support

Example fix

// before
run_terminal_attach(id, takeover)?;

// after
if crate::platform::capabilities().direct_terminal_attach {
    run_terminal_attach(id, takeover)?;
} else {
    run_terminal_session_observer(id)?;
}

if !crate::platform::capabilities().direct_terminal_attach {
    return run_terminal_session_observer(terminal_id);
}

fn supports_direct_attach() -> bool {
    crate::platform::capabilities().direct_terminal_attach
}

match run_terminal_attach(id, takeover) {
    Err(e) if e.kind() == io::ErrorKind::Unsupported => fallback_observer(id),
    r => r,
}

When it happens

Trigger: Invoking the direct terminal attach code path on a Windows build of herdr (e.g. the CLI attach command resolving to run_terminal_attach with cfg(windows) active). Any call fails unconditionally.

Common situations: Users or scripts written against Linux/macOS behavior run unchanged on Windows; automation assuming raw-mode attach exists cross-platform.

Related errors

• failed to {operation} managed plugin checkout at {}; close a
• api request line is too large
• timed out reading api request
• timed out waiting for app response after {} ms
• app response channel closed

AI-assisted analysis of herdrdev/herdr@f457cff4f2 (2026-08-28). Data as JSON: /api/errors/1e9b58bda0437779. Report an issue: GitHub.