blog · · engineering

Reading the peer's log was itself a filesystem event

On Linux the outl desktop app opened and then reloaded forever. Nothing was writing to the workspace. The filesystem watcher decided whether to wake the frontend by looking only at the path an event named, never at what the event said happened, and `reload_workspace` replays a peer's ops by opening `ops-<actor>.jsonl` read-only. On Linux that open is an event. So the consumer of `peer-ops-changed` was a producer in the stream it consumed, and the loop could not end. The fix is ten lines of event-kind filter. What makes it interesting is why the path-only filter was correct on macOS and Windows for four months, why the new check is a denylist rather than an allowlist, and that `outl serve` still has both halves of the same shape.

A
10 min read

On Linux the desktop app opened, reloaded the workspace, and then never stopped reloading.

Nothing was writing to the workspace. No peer was connected, no editor was open on the folder, no sync pass was running. One ops/ops-<actor>.jsonl file belonging to a peer, a few dozen lines long, was being read, and read, and read.

The reading is what kept waking the reader.

the watcher only watches ops/, because the first cut already fed itself

The desktop’s filesystem watcher is small. It wraps notify plus notify-debouncer-full, sits on the workspace’s ops/ directory, and emits one Tauri event called peer-ops-changed when a peer’s op log grows. crates/outl-desktop/src/lib/events.ts subscribes to it, AppShell.tsx calls reloadWorkspace(), and the outline re-renders with whatever the peer wrote. That is the whole feature.

It watches ops/ and nothing else, and the module doc in crates/outl-desktop/src-tauri/src/fs_watcher.rs is explicit about why:

//! 1. `reload_workspace` runs (`peer-ops-changed` from the frontend).
//! 2. It calls `reproject_page` which writes `journals/today.md`.
//! 3. The watcher (when scoped at the root) sees the `.md` change.
//! 4. Watcher emits `peer-ops-changed`.
//! 5. Frontend reloads → goto 1.

So this file already knew about a reload loop. It had been through one, named it, and taken the obvious lesson from it: do not watch the files you write. start_watcher scopes the watch to ops/ with RecursiveMode::NonRecursive, our own .md projections land outside it, and the loop was gone.

The lesson it took was about writes.

the filter asked where, and never what

Inside ops/ there is still noise to refuse. The debouncer hands over a batch every 150ms, and the batch can contain our own actor’s file, a lock flap, an atomic write’s .tmp stage. So there is a filter, and before this change it was one function:

fn path_is_interesting(path: &Path, own_ops_file: &str) -> bool {
    let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
        return false;
    };
    if name.starts_with(".outl-") || name.ends_with(".lock") || name.ends_with(".tmp") {
        return false;
    }
    if name.starts_with("ops-") && name.ends_with(".jsonl") {
        return name != own_ops_file;
    }
    false
}

Read it as a question and it is: is this a peer’s op log? Every clause is about the name of a file. Nothing in events_should_emit asked the other question a filesystem event answers, which is what happened to that file. A notify::Event carries an EventKind alongside its paths, and the old filter walked straight past it.

That is not sloppiness so much as a default. When you think of a file watcher you think of changes, because that is what the phrase means, and every kind you can name off the top of your head is a change. The filter was correct for the kinds I had in mind. The problem is the one I did not.

replaying a peer’s log means opening a peer’s log

reload_workspace on the Rust side goes through outl_actions::SyncEngine::reload_workspace, in crates/outl-actions/src/sync.rs, and its first two statements are the whole story:

let ops_dir = self.workspace_root.join("ops");
let storage = JsonlStorage::open(ops_dir, self.actor)

Opening the storage reads every actor’s log. On the full-replay path that lands in read_ops_file_into in crates/outl-core/src/storage/jsonl/read.rs, which is as literal as it sounds:

let file = match File::open(path) {
    Ok(f) => f,
    Err(e) if e.kind() == std::io::ErrorKind::NotFound => return,

One File::open per peer file, a BufReader to the end, then the handle drops and the file closes. That is the correct way to replay an append-only log and there is nothing to fix about it.

Put the two halves next to each other and the loop writes itself. The watcher wakes the frontend. The frontend asks the backend to reload. The reload opens ops/ops-<peer>.jsonl. The open is an event on a watched path. path_is_interesting says yes, because it is genuinely a peer’s op log. peer-ops-changed fires again.

The handler for an event stream was a producer in the stream it consumed. Once that is true, no amount of debouncing ends it; the 150ms window just sets the frequency. onPeerChange in AppShell.tsx coalesces reloads and refuses to run one while the user is editing, which is why the window stayed usable enough to notice rather than simply dying, and which also meant the symptom read as “the app is busy” instead of “the app is in a loop”.

This is the same shape as a status check that broke the sync it was measuring, and it is worth saying what the two have in common, because it is not “be careful”. In both cases the component was correct in isolation and the system had a feedback edge nobody had drawn. There, observing took a route from the thing being observed. Here, reading left a trace the reader was subscribed to.

Linux reports the read, and the two platforms I develop on do not

notify models this directly. Alongside Create, Modify and Remove, EventKind has an Access arm, and AccessKind splits into Open(AccessMode) and Close(AccessMode), among others. The AccessMode on a close is the interesting one: Read and Write are separate variants, which only makes sense as a model of a system that distinguishes a close after a write from a close with nothing written.

That distinction is inotify’s. Linux’s watcher has had IN_OPEN, IN_CLOSE_WRITE and IN_CLOSE_NOWRITE for its whole life, and notify’s inotify backend surfaces them as Access(Open(..)), Access(Close(Write)) and Access(Close(Read)). The pinned versions here are notify 8.2.1 and notify-types 2.2.0, and #481 records the mask-to-variant mapping as checked against those sources.

macOS and Windows have no equivalent in what their backends deliver. I cannot cite their source from here, so I will give the evidence I actually have: the desktop client shipped in 0.8.0 on 11 July 2026 with this watcher, I run it on macOS daily, and in the near four months to 2 November nobody on macOS or Windows reported a reload loop. The first report was Linux, as issue #474.

So the honest statement about the old filter is not that it was wrong. It was right on two platforms and wrong on one, and the two were the two I develop on. A path-based filter is a complete filter exactly when the platform does not tell you about reads. That is a premise, it was never written down anywhere, and it stopped holding the moment somebody ran the build on a machine with inotify under it.

a denylist, because the kind nobody has enumerated has to stay interesting

The fix is ten lines:

fn event_kind_is_interesting(kind: &notify::EventKind) -> bool {
    use notify::event::{AccessKind, AccessMode};
    match kind {
        notify::EventKind::Access(AccessKind::Close(AccessMode::Write)) => true,
        notify::EventKind::Access(_) => false,
        _ => true,
    }
}

and one && in the caller:

events.iter().any(|ev| {
    event_kind_is_interesting(&ev.kind)
        && ev
            .paths
            .iter()
            .any(|p| path_is_interesting(p, own_ops_file))
})

The obvious alternative was an allowlist: emit on Create, Modify and Remove, drop everything else. It is tighter, it reads better, and it is the shape I would normally argue for, because a denylist fails open and an allowlist fails closed.

Failing open is the correct direction here, and that is the whole argument for the _ => true arm. EventKind also carries Any and Other, which are what a backend emits when it cannot classify what it saw. An allowlist would silently drop those, and a dropped event in this watcher means a peer’s edit sits on disk while the screen shows the old page until something else happens to fire. A watcher whose job is to notice should not go quiet on a kind nobody enumerated. The specific thing that loops is reads, and reads are now refused by name.

The cost of choosing that direction is stated rather than avoided: if some backend ever reports a pure read as something other than Access, this filter passes it, and the loop is back. I would rather carry that than ship a filter that can fall silent.

Close(Write) survives, because this process writes peer files too

The one Access kind kept is Close(AccessMode::Write), and it is not a hedge. It is IN_CLOSE_WRITE, which only fires when the file was modified before the close, so it is a completed write by definition.

It also has a real producer inside this very process. outl-sync-iroh’s ingest_received_ops buckets received ops by op.actor and appends them to ops/ops-<actor>.jsonl, which for every op that came from a peer is a peer’s file, written by us. That write is exactly the moment the frontend must reload. Dropping every Access kind without exception would have cost nothing on a Modify-reporting backend and would have been one more unexamined premise.

So the chain now terminates in the right place. Our ingest writes a peer file, Close(Write) emits, the frontend reloads, the reload opens every peer file, and those opens and closes are read artefacts that go nowhere.

the tests construct the events they test, which is the hole they leave

Five tests went in beside the existing filter-policy tests, written before the fix so they fail against the path-only filter:

#[test]
fn peer_access_close_read_does_not_emit() {
    // CLOSE_NOWRITE: the file was closed without being modified,
    // i.e. a pure read. Same loop as the open() case above.
    let events = vec![debounced(
        EventKind::Access(AccessKind::Close(AccessMode::Read)),
        "/ws/ops/ops-01HPEER000000000000000000.jsonl",
    )];
    assert!(!events_should_emit(&events, OWN));
}

peer_access_open_does_not_emit and peer_access_close_write_still_emits are the other two that matter, and the pair is the point: a filter that refused everything would pass every negative test ever written, so the one asserting that a real write still emits is doing as much work as the ones asserting the loop is closed.

Here is what they do not do. Every one of them builds a DebouncedEvent by hand. None of them touches a real inotify watch, opens a real file, or runs a real debouncer. They pin the policy, which is the half a regression is most likely to break, and they run identically on macOS, where the events they describe never occur.

The premise underneath all five, that Linux delivers Access(Open(Any)) and Access(Close(Read)) for a read of a watched file, is held up by reading the crate and by one person running the build on one Linux machine. CI runs a Linux job and these tests pass there, which proves nothing about the premise, because they would pass on a kernel with no inotify at all. That gap is deliberate, since a test that stands up a real watcher and sleeps for a debounce window is a flaky test on a loaded runner, but it should be named rather than implied by a green check.

outl serve has both conditions and no fix

The desktop is not the only consumer of notify in this repo. outl serve, the background daemon, is the other, and the shape there is identical.

It watches pages/ and journals/ non-recursively on a 200ms debounce. Its filter, is_workspace_md in crates/outl-ws/src/layout.rs, checks the extension, refuses dotfiles, and checks the directory prefix. Three questions, all about the path, none about the kind. And what it does with a matching event is call reconcile_md, whose first statement in crates/outl-md/src/reconcile.rs is fs::read_to_string(md_path).

Both conditions of the desktop bug hold there: a path-only filter, and a handler that reads the file the event named. I have not run the daemon on Linux to watch it spin, so I am reporting the shape and not a measurement. It would be the cheaper version of the same loop, since the sidecar hash short-circuits before any op is emitted, but it would still be one read and one hash per event forever, and it would never settle.

The fix that landed is scoped to one file in one crate, which is the right size for a fix to a reported crash and the wrong size for the finding underneath it. The second half is mine to file.

what I would take from this

The rule I had written down was “do not watch the files you write”, and it is a true rule that does not cover this. Reading is not writing, and on one of the three platforms outl ships to, the kernel disagrees that the distinction matters for the purpose of telling you something happened.

The better question, the one that generalises past filesystems, is not “what do I write” but what does my handler do that the thing waking it can see? An event stream has a feedback edge whenever the consumer touches the subject of the event at all, and “I only looked” is not an answer, because looking is observable in more systems than it is not.

And the platform asymmetry is the part worth carrying. A filter that reads as complete on your own machine can be complete only because of a premise your machine happens to satisfy. The premise here was one sentence long and was never written anywhere, so there was nothing for a reviewer to disagree with. It is in the module doc now, next to the first loop it belongs beside, which is the most that documentation can do about a class of bug whose whole trick is that it cannot be seen from where the code is written. The same shape, on a different axis, as the two ways outl dies on open that both happen before any of my code runs.

The filter is in the outl repository, at crates/outl-desktop/src-tauri/src/fs_watcher.rs.