# ADR-0047: Disk writes are announced with `fs.changed`

- **Status:** Accepted
- **Date:** 2026-08-18
- **Deciders:** jka
- **Decision:** D47

## Context

A file created by the agent did not appear in the files pane until the user
refreshed by hand. The core broadcast `buffer.changed` for edits to open buffers, but
nothing for writes straight to disk.

## Decision

- **An event.** Operations that write to disk outside a buffer emit
  `fs.changed {path}` with an absolute path. The agent forwards it when it creates a
  file or edits a closed one. `file.save` does not emit it, because the saving GUI
  already refreshes locally. The GUI repaints the git pane on any change and the
  files pane when the change is in a directory it is showing.
- **A manual refresh.** The files pane header gets a `⟳` refresh button, like the git
  pane, for changes rio did not make.
- **Refresh on focus return.** When the application regains operating-system focus,
  the shown pane refreshes once. This is detected from focus events on the top-level
  window, debounced, and only on a real change from "another application has focus"
  to "rio has focus". It is not polling.

## Consequences

- Writes rio makes appear in every connected frontend without user action.
- Changes made outside rio (another editor, `git pull`, a build) appear when the user
  returns to rio or presses refresh.
- rio still has no file watcher; a watcher in the core that emits `fs.changed` is the
  deferred complete answer, with its dependency and per-platform cost.
- ADR-0094 extended the same triggers to open buffers.