{"record":{"id":"1e9b58bda0437779","repo":"herdrdev/herdr","slug":"direct-terminal-attach-is-not-supported-on-windows","errorCode":null,"errorMessage":"direct terminal attach is not supported on Windows yet","messagePattern":"direct terminal attach is not supported on Windows yet","errorType":"error_code","errorClass":"io::Error","httpStatus":null,"severity":"warning","filePath":"src/client/mod.rs","lineNumber":953,"sourceCode":"    )\n}\n\n/// Runs a direct terminal attach client.\n#[cfg(unix)]\npub fn run_terminal_attach(terminal_id: String, takeover: bool) -> io::Result<()> {\n    run_client_with_mode(\n        RenderEncoding::TerminalAnsi,\n        Some((terminal_id, takeover)),\n        Some(AttachEscapeState::default()),\n        \"attaching to terminal\",\n    )\n}\n\n/// Direct terminal attach is Unix raw-byte input only until Windows gets a semantic attach path.\n#[cfg(windows)]\npub fn run_terminal_attach(_terminal_id: String, _takeover: bool) -> io::Result<()> {\n    debug_assert!(!crate::platform::capabilities().direct_terminal_attach);\n    Err(io::Error::new(\n        io::ErrorKind::Unsupported,\n        \"direct terminal attach is not supported on Windows yet\",\n    ))\n}\n\n/// Runs a read-only terminal session observer and prints one JSON envelope per frame.\npub fn run_terminal_session_observe(target: String, cols: u16, rows: u16) -> io::Result<()> {\n    let mut stream =\n        connect_terminal_session_stream(target.clone(), cols, rows, \"observing terminal session\")?;\n    write_to_server(&mut stream, &ClientMessage::ObserveTerminal { target })?;\n    write_terminal_session_output(stream)\n}\n\n/// Runs a writable terminal session controller.\npub fn run_terminal_session_control(\n    target: String,\n    takeover: bool,\n    cols: u16,","sourceCodeStart":935,"sourceCodeEnd":971,"githubUrl":"https://github.com/herdrdev/herdr/blob/f457cff4f2648eee85d176f8a41861241d4e8428/src/client/mod.rs#L935-L971","documentation":"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.","triggerScenarios":"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.","commonSituations":"Users or scripts written against Linux/macOS behavior run unchanged on Windows; automation assuming raw-mode attach exists cross-platform.","solutions":["Use the supported Windows path (semantic attach / client session stream) instead of direct attach","Gate scripts by platform: only call direct attach when the capability is advertised, not by OS guess","Track herdr releases for Windows direct attach support"],"exampleFix":"// before\nrun_terminal_attach(id, takeover)?;\n\n// after\nif crate::platform::capabilities().direct_terminal_attach {\n    run_terminal_attach(id, takeover)?;\n} else {\n    run_terminal_session_observer(id)?;\n}","handlingStrategy":"type-guard","validationCode":"if !crate::platform::capabilities().direct_terminal_attach {\n    return run_terminal_session_observer(terminal_id);\n}","typeGuard":"fn supports_direct_attach() -> bool {\n    crate::platform::capabilities().direct_terminal_attach\n}","tryCatchPattern":"match run_terminal_attach(id, takeover) {\n    Err(e) if e.kind() == io::ErrorKind::Unsupported => fallback_observer(id),\n    r => r,\n}","preventionTips":["Branch on platform capabilities, not cfg at call sites","Have a semantic-attach fallback ready on platforms without raw-mode attach"],"tags":["windows","platform-unsupported","terminal-attach","rust"],"backgroundTag":"unsupported-platform-operation","analyzedSha":"f457cff4f2648eee85d176f8a41861241d4e8428","analyzedAt":"2026-08-28T15:41:09.197Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}