On X11 a copy is a promise to answer later
The TUI's status line read `yanked 3 block(s) → clipboard` and `xclip -o -selection clipboard` answered `Error: target STRING not available`. Nothing had failed: on X11 the selection owner serves the clipboard, arboard runs that owner in a thread tied to the Clipboard value, and copy_to_os_clipboard built a fresh one per yank and dropped it the instant set_text returned Ok. One process-wide handle fixes it, and then a second trap closes: a static is never dropped, and arboard hands the selection to a clipboard manager only in Drop, so the handover had to be called by hand at quit. That trades 'the text is gone immediately on a bare session' for 'the text is gone if the process is killed', and leaves PRIMARY, Wayland and a chord with no SSH fallback as named costs.
The status line read yanked 3 block(s) → clipboard.
In the next pane, xclip -o -selection clipboard answered Error: target STRING not available. Nothing had gone wrong on the way there. arboard’s set_text returned Ok, outl reported exactly what set_text told it, and the three blocks were in no clipboard anywhere on the machine.
That is issue #472. The session is a window manager and nothing else: XMonad, urxvt, $XDG_CURRENT_DESKTOP empty, no clipboard manager running.
on X11 a copy is a promise to answer later, not a write
The comment that now sits above the fix in crates/outl-tui/src/actions/yank.rs states the thing the whole bug turns on: on X11 there is no system clipboard buffer, and the selection owner serves the contents to whoever asks.
CLIPBOARD is a name the X server associates with a window. Copying registers your process against that name. Pasting is a request routed back to the registered window, which answers with the bytes in whatever representation was asked for. The data never leaves the copying process until somebody wants it, which is why the error is phrased the way it is: target STRING not available is a failed conversation, not an empty buffer. xclip asked, and either nobody was there or nobody could answer in that form.
So Ok from set_text means the registration went through and something is standing by. It does not mean the text is anywhere. A program that copies and exits has not copied. The owner is gone, the name has no window behind it, and every paste after that fails.
Almost nobody meets this, because almost everybody runs a clipboard manager. A clipboard manager is a daemon whose entire job is to be the process that does not exit: it takes the contents over from a departing owner and then serves them itself. Every desktop environment ships one. A window manager is not a desktop environment, and XMonad ships nothing of the kind.
the handle is the owner, and it was built once per yank
copy_to_os_clipboard constructed a fresh arboard::Clipboard, called set_text on it, and let it fall off the end of the function. arboard runs the X11 server side in a background thread tied to that value, so the owner was created, registered, and destroyed inside one function call. By the time the status line rendered, the thread that was supposed to answer the paste had already been torn down.
With a clipboard manager running, that is invisible. The handle is dropped, arboard offers the contents to the manager, the manager takes them, and a paste a minute later works. Without one, the offer goes nowhere and the text ends in the same microsecond it was reported as copied.
The thing that makes this worth writing down is that the identical shape is still in the repo, one file over, and it is correct there. crates/outl-tui/src/actions/paste.rs:
fn read_os_clipboard() -> Option<String> {
arboard::Clipboard::new()
.and_then(|mut c| c.get_text())
.ok()
}
A read is a question put to whoever currently owns the selection. It needs a connection for the duration of the question and nothing afterwards, so building and dropping a handle per call is exactly right. A write is an offer to serve, and an offer you withdraw before anyone can accept is not an offer. Same two lines of arboard API, opposite lifetime requirements, and the asymmetry is entirely a property of the protocol rather than of the library.
one handle for the process, retried when it fails
The write side keeps a single handle now:
static CLIPBOARD: std::sync::Mutex<Option<arboard::Clipboard>> = std::sync::Mutex::new(None);
fn copy_to_os_clipboard(text: &str) -> bool {
// A poisoned lock still guards a usable `Option`, and giving up on it
// would disable this path for the rest of the session.
let mut guard = CLIPBOARD.lock().unwrap_or_else(|e| e.into_inner());
if guard.is_none() {
// Retried on every call while it fails, so a display that shows
// up later (or a headless run) behaves exactly as before.
*guard = arboard::Clipboard::new().ok();
}
let ok = guard
.as_mut()
.is_some_and(|c| c.set_text(text.to_string()).is_ok());
if !ok {
// A dead display connection (X server restart, dropped SSH
// forwarding) would otherwise fail every later yank. Dropping the
// handle makes the next call reconnect, as a fresh `Clipboard`
// per yank used to.
*guard = None;
}
ok
}
Two things in there are not the fix and are what keep the fix from costing anything.
The handle is built lazily, on the first yank that needs it. A session that never yanks never opens a display connection, and a headless run gets None from Clipboard::new().ok() on every call, retries on the next one, and behaves exactly as it did before. The per-yank construction was also, accidentally, a per-yank retry; the is_none() branch is what keeps that property.
A failed write drops the handle. This is the half that the previous code got for free. An X server restart or a dropped SSH forwarding leaves a Clipboard whose connection is dead, and a cached dead handle would fail every yank for the rest of the session. Setting it back to None means the next yank reconnects.
Both of those read as defensive extras until you notice that the old code had them by construction and the new code has to ask for them. That is the usual shape of a caching change: the thing you are adding is cheap, and the properties you are silently removing are the bill.
a static is never dropped, so the handover had to be called by hand
Then the second trap, which is the first one wearing the opposite sign.
arboard offers the selection to a clipboard manager in Drop. A static is never dropped. So the first commit, which fixed the bare session, broke the case that had been working: on a machine with a clipboard manager, the TUI now held the selection until the process ended and then vanished without ever making the offer. Users with a desktop environment would have gone from “quitting keeps the text” to “quitting loses it”, which is a strictly worse trade than the bug being fixed.
The second commit calls the drop by hand:
pub(crate) fn release_os_clipboard() {
let mut guard = CLIPBOARD.lock().unwrap_or_else(|e| e.into_inner());
*guard = None;
}
Four lines, and the only interesting thing about them is where they are called from. crates/outl-tui/src/runtime/mod.rs:
let result = event_loop(
&mut terminal,
workspace_root,
workspace,
actor,
theme,
shared_workspace,
backlinks_newest_first,
global_cfg.tui.icons,
config_warning,
);
crate::actions::yank::release_os_clipboard();
After the event loop, before the terminal is handed back, on the Ok path and the Err path alike, because a TUI that exits with an error has still taken the user’s last yank hostage. The doc comment on release_os_clipboard records the bound this inherits: at most 100 ms of waiting for the manager. That 100 ms is spent inside the alternate screen, before LeaveAlternateScreen and disable_raw_mode run, which is the wrong order if you care about perceived quit latency and the right order if you care about the handover happening at all.
the handover went from every yank to exactly one, and that is a regression
main offered the contents to a clipboard manager on every single yank, because every single yank dropped a handle. This branch offers them once, at a normal quit.
A panic does not reach it. The panic hook in crates/outl-tui/src/runtime/terminal.rs restores the terminal and chains to the previous hook, and it deliberately does not touch the clipboard:
let _ = disable_raw_mode();
let _ = execute!(std::io::stdout(), LeaveAlternateScreen);
let _ = execute!(std::io::stdout(), crossterm::cursor::Show);
previous(info);
It must not. std::panic::set_hook installs a hook that runs before unwinding, so if the panic happened inside copy_to_os_clipboard the guard on CLIPBOARD is still alive, and a hook that took the same non-reentrant lock would hang the process instead of printing the panic. The poisoned-lock recovery in copy_to_os_clipboard handles the aftermath of that panic; it cannot help a hook that deadlocks before the aftermath exists.
SIGTERM does not reach it either, nor does a closed terminal window, nor SIGKILL. So on a machine with a clipboard manager, the yank now survives a normal quit and does not survive a crash, where before it survived both. That is a real loss and it is in docs/tui.md in those words: a crash, a kill or a closed terminal window skips the handover, so the text then survives only if the manager had already copied it. Which, for a manager that watches for owner changes rather than waiting to be handed something, it usually will have. For one that relies on the handover, it will not.
the CI has no display, so the evidence is two runs of xclip
There is no automated test for this. cargo test -p outl-tui -p outl-shortcuts passes 306 tests and not one of them can register a selection, because the runner has no X11 session: nothing to own CLIPBOARD, nothing to ask. This is the same category as 4,291 assertions that cannot see a pixel, and the honest response is the same one: measure the real thing by hand and write down what the measurement was.
What it was: the same workspace, the same marker text, the TUI left running, arboard 3.6.1, XMonad, no clipboard manager.
xclip -o -selection clipboard | |
|---|---|
main (a Clipboard per yank) | Error: target STRING not available |
| this branch (one shared handle) | the yanked text |
Two rows, which is the entire experimental record for a change of 74 insertions across five files. And the PR says the part that makes it weaker than it looks: that check was run on the first commit, before the handle was dropped at quit, and the handover to a clipboard manager has not been checked by hand at all. The reasoning for it is sound and it is reasoning, not a reading.
PRIMARY, Wayland, and a chord with no fallback
Three things this does not do, each of them a decision rather than an oversight.
yy fills CLIPBOARD only. X11 has a second selection, PRIMARY, which is the one a mouse highlight fills and which urxvt pastes on Shift+Insert. A user on that terminal can yank a block, hit the paste chord they use for everything else, and get whatever they last dragged a cursor over. Filling both would fix it and would also overwrite the user’s mouse selection on every yy, which is a different surprise with the same shape. It is left as an open question rather than answered quietly in this change.
Wayland is claimed and not tested. crates/outl-tui/Cargo.toml declares arboard = { version = "3", default-features = false }, which leaves out wayland-data-control, so a Wayland session reaches the clipboard through XWayland and inherits everything above. That follows from the manifest rather than from a run. It is worth knowing which manifest that is: the release workflow’s build step is cargo build --release with -p outl-cli --bin outl, so the arboard in a shipped outl is the one this crate asked for, and not a feature-unified build that also drags in the desktop client’s clipboard plugin. The earlier version of docs/tui.md claimed Wayland kept the text after quit. It did not, and the doc says so now.
y r has no OSC 52 path. Following copy_to_os_clipboard to its callers is how you find this. yank_current and yank_visual_range go through copy_markdown_to_clipboard, which tries arboard and then writes an OSC 52 escape so the copy reaches the outer clipboard over SSH, tmux or Crostini. yank_current_ref and yank_current_embed, the y r chord and the /refer slash command, call copy_to_os_clipboard directly:
self.status = clipboard_message("ref", &token, copy_to_os_clipboard(&token));
So on a remote session yy reaches your real clipboard and y r reaches nothing, and the status line distinguishes the two correctly by saying (clipboard unavailable). The fix in this PR helps y r on a bare local X11 session, because it is the same function. It does not give it the remote path, and that gap predates this change by a long way.
The lesson is not about clipboards. It is that Ok is a statement about the call you just made and never about the state of the world afterwards, and the gap between those two is exactly as wide as the lifetime of whatever the call registered. set_text was telling the truth the whole time. It said the registration succeeded. The question nobody had asked was how long outl intended to stay registered, and on X11 that question is the entire feature.
Everything above is a property of a display server protocol that outl cannot change, so what is left is to say which parts of it the product does not handle and where. I would rather ship that written down, the same way a declined local-network permission that looks exactly like an empty LAN is written down, than have a user discover by pasting into a browser that their notes went nowhere.
The fix is crates/outl-tui/src/actions/yank.rs and the call site in crates/outl-tui/src/runtime/mod.rs, in the outl repository.