feat(runtimed): notebook URI scheme; daemons coordinate as Automerge peers

[rgbkrk]

Current triage (2026-05-05)

Status: Keep open as an architecture epic. Partially stale against main at e5d48e44.
Priority: P3 backlog for now; not a stable blocker unless cross-daemon/remote workflows become common.

Current code notes:

• PR fix(runt): open ephemeral notebooks by id #2561 improved runt open <uuid> for ephemeral notebooks, but it does not implement notebook URIs, cross-daemon ownership, or daemon-to-daemon peer routing.
• Current ownership remains in-process only through the room/path index; opening still flows through path/string-style APIs rather than a URI transport selector.
• Frame references in the original body should be read with the current protocol map: 0x06 is PoolStateSync, 0x07 is SessionControl, and PutBlob is drafted as 0x08.

Summary

A notebook is identified by a URI, not a bare filesystem path. Daemons participate as Automerge peers of each other for any notebook URI; at most one daemon is the owner (runs the kernel, writes the file) and the rest connect as sync peers over whatever transport fits the URI scheme. The same primitive serves three cases that today need three different answers:

Case	Today	With this primitive
Two local daemons opened the same .ipynb	Silent autosave clobber (see linked bug)	Second daemon dials the first; one room, one writer
Notebook lives on a remote box, edit it from a laptop	No story (see #1334)	URI is ssh://host/path/nb.ipynb; local daemon dials remote daemon over SSH
Multiple agents share one notebook	Pile of MCP proxies, all racing to autosave	All speak to the owning daemon, sync converges

The closed predecessors (#832, #1332, #1333) already built the daemon-as-peer model in-process and as a subprocess. This issue is "extend the same model across daemon process boundaries."

URI scheme

Every connect_notebook call accepts a URI. The MCP wire stays string-typed. Bare paths keep working as a shorthand for file://.

Scheme	Owner location	Transport	Notes
file:///abs/path/nb.ipynb	Same machine	Local Unix socket / named pipe	Today's path, with explicit ownership
ssh://[user@]host[:port]/path/nb.ipynb	Remote machine	SSH stdio (ssh host runt sync-serve --notebook /path)	Replaces the agent-forwarding model in #1334
(open) daemon://socket-or-host/uuid	Whoever holds the doc	Direct connect to a daemon socket	Useful for "attach me to whatever room this daemon already has," no path involved

The URI is the key. file:///nb.ipynb opened by daemon A and daemon B resolves to the same room; one of them owns it, the other is a peer.

Ownership

Exactly one daemon is the owner of a URI at any given moment. The owner:

• Reads and writes the .ipynb (or whatever the scheme's storage is).
• Runs the kernel for that notebook.
• Holds the canonical Automerge doc.

Everyone else is a peer that syncs the doc and drives the UI / MCP / agent locally.

Discovery on the same machine: the owning daemon writes a tiny presence file in a known cache dir (~/.cache/runtimed/owners/{sha256(uri)}.json) with pid, socket_path, channel, heartbeat_at. Other daemons consult the directory before claiming a URI; if they find a live owner, they dial it as a peer instead.

Discovery across machines: the local daemon dials the remote one explicitly via the URI's transport (SSH for ssh://). The remote daemon's "is this URI already owned" check is local on its side.

Ownership transfer: owner is whoever the kernel was last launched from. If the kernel is restarted on a different machine, ownership transfers along with it. This tracks user intent ("compute moved, doc follows"). Open question: how to make transfer atomic without dropping in-flight executions.

Crash recovery: lockfile sidechannels carry a heartbeat. If the heartbeat goes stale and the PID is dead, the next daemon to ask claims it and reads .ipynb from disk.

What stays local on each box

The kernel's Jupyter transport (shell, iopub, control, stdin, heartbeat: ZMQ today, IPC sockets after #1813) is internal to whichever box the kernel runs on. Nothing about it crosses a daemon boundary. The cross-daemon channel only carries:

• NotebookDoc Automerge sync frames
• RuntimeStateDoc Automerge sync frames
• Blob frames (already designed in feat(runtimed): process-isolated runtime agent with blob relay #1333 as frame 0x06)

Kernel control commands (interrupt, restart, shutdown) become writes to RuntimeStateDoc that the owning daemon observes and dispatches to its local kernel. Today's execution is already CRDT-driven (coordinator writes queued, runtime agent transitions to running/done). Pushing interrupt and restart onto the same surface means the entire daemon-to-daemon protocol is "Automerge bytes both ways," with no parallel RPC channel.

Transport-agnostic protocol

The wire format is the existing notebook-sync framing. SSH stdio, Unix sockets, named pipes, and (in principle) HTTPS websockets all carry the same frames. That answers minrk's question on #1334: yes, an HTTP-based transport can carry the protocol; the protocol does not depend on it. The hard question becomes auth, not wire shape, and that is scoped per-transport (SSH config for ssh://, socket access for file://, bearer token + CORS for any future HTTPS variant).

What needs to change

1. URI parser + scheme dispatch in runt-mcp and the daemon's connect_notebook handler. file:// continues to work as today; new schemes route through a transport-selector.
2. Ownership table on disk: ~/.cache/runtimed/owners/{hash}.json with heartbeat. Check before creating a room; bail out and dial the owner if it exists.
3. Owner-side sync server: each daemon already runs notebook-sync over Unix sockets. Generalize so it can accept inbound peer connections from another daemon, not only frontend / MCP clients.
4. Peer-side dialer: when the local daemon resolves a URI to a remote owner, it spawns the right transport (ssh ... runt sync-serve --notebook /path for SSH; direct socket connect for file:// cross-daemon) and pipes Automerge frames through.
5. Kernel-control via RuntimeStateDoc: replace the remaining RPC paths (interrupt, restart, shutdown) with CRDT writes the owner observes.
6. Failover for ownership transfer (out-of-scope for v1, but worth designing space for): when a kernel-restart targets a different machine, transfer ownership cleanly without losing in-flight execution state.

Scope

In scope: the same-machine cross-daemon case (which fixes the autosave-collision bug #2285) and the SSH transport (which is #1334).

Out of scope: HTTP / HTTPS transport (interesting for the JupyterHub case minrk raised on #1334; tracked separately if we ever take it on), publishing notebook URIs as a stable shareable identity (closer to a "join my notebook" share-link feature), GUI for picking remote hosts.

Related

• design(desktop): SSH compute through a remote daemon runtime peer #1334: SSH remote runtimes; becomes one transport implementation of this primitive
• bug(runtimed): two daemons sharing autosave path silently overwrite each other's writes #2285: bug where two local daemons clobber each other's autosaves; the same-machine special case whose principled fix is this primitive
• Runtime agents: decompose kernel ownership into per-runtime Automerge peers #832, feat(runtimed): RoomKernel as Automerge peer — own actor ID and doc replica #1332, feat(runtimed): process-isolated runtime agent with blob relay #1333: daemons-as-peers, in-process and subprocess (shipped). This issue extends the model across daemons.
• Switch kernel launch to IPC transport (supersedes #1772) #1813: replace TCP+ZeroMQ kernel transport with IPC. Independent of this work; the kernel transport stays local on each box regardless. Worth doing on its own merits.

[rgbkrk]

Closing this as superseded by the newer identity/auth ADR direction. The useful part of this issue was pointing at a room-host / deployment-topology question, but the current framing conflates URI, daemon ownership, file persistence, runtime placement, and authorization. The accepted identity model now separates room identity, per-room ACL authorization, connection-scoped auth, and runtime_peer/editor roles.\n\nFollow-up should be a fresh ADR or issue around the intended topology: Cloudflare/hosted room as the document engine with Anaconda/OIDC auth, while JupyterHub or another runtime service provides compute as a scoped runtime_peer. #2285 remains the concrete local autosave collision bug/stopgap.