docs: stop claiming events.subscribe delivers events

docs/reference/ipc.md said in four places that the server pushes
event envelopes after events.subscribe; the op has always answered
not-implemented (ops::EVENTS_SUBSCRIBE in roost-engine/src/ipc.rs).
All four sites now document the real error reply, point callers at
polling, and carry a forward note: HS-1 delivers events as atomic
{revision, events[]} EventBatches (types landed in roost-ipc on this
branch). The event catalog stays, reframed as the shape a future
push will carry (plan 033 / HS-0, D7).

Also sweeps the profile docs for the new Session profile: paths.md
gains the reserved-profile row, the session path table (with the
-dev split), and the ROOST_BUNDLE_PROFILE note; ipc.md points at it
from the socket-path section. setup.md's profile table is
deliberately untouched — it is scoped to UI profiles and roostctl
targets, which Session is not.

Docs-only commit; self-reviewed (paths and op behavior were
code-verified earlier in this branch's commits).

Gate: make check + make docs (strict).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XdmwyhPxKnPHFFiqAMyUMC

Author: charliek

docs/reference/ipc.md

@@ -24,6 +24,12 @@ than one is live, it reports the actual candidates and requires selection.
 (The `linux` profile also resolves on macOS, as `~/Library/Caches/Roost-linux/`,
 but nothing ships or launches it there.)
 
+A fifth socket path, `Session` (`~/Library/Caches/RoostSession/roost.sock`
+on macOS, `$XDG_RUNTIME_DIR/roost-session/roost.sock` on Linux), is
+**reserved** for the future `roost-session` daemon (HS-1). Nothing binds
+it yet, it is not a `roostctl --target` value, and `roostctl` never probes
+it — see [`paths.md`](paths.md#session-profile-reserved).
+
 ## Wire format
 
 * **Framing:** newline-delimited JSON. One JSON object per line.
@@ -42,10 +48,11 @@ but nothing ships or launches it there.)
   `{"id": "<string>", "ok": true, "result": {...}}`.
 * **Response envelope (error):**
   `{"id": "<string>", "ok": false, "error": {"code": "<kebab>", "message": "<string>"}}`.
-* **Event envelope** (server-push, unsolicited, only sent after
-  `events.subscribe`):
+* **Event envelope** (server-push, unsolicited — **not delivered
+  today**; see [`events.subscribe`](#eventssubscribe)):
   `{"event": "<dotted-name>", "data": {...}}` — no `id`, no response
-  expected.
+  expected. This is the shape a future push will use; the catalog in
+  [Events](#events) below documents it in advance.
 * **Bytes payloads** (e.g. `tab.write.data`, and any future binary
   field): **base64-encoded strings** using the standard alphabet,
   no padding stripping. Tested for binary fidelity (`0x00..0xff`
@@ -1009,26 +1016,40 @@ state live on the UI side.
 
 ### `events.subscribe`
 
-Opt-in to the event stream. After the response, the server pushes
-`{"event": ..., "data": ...}` envelopes on the same connection until
-the connection closes.
-
-Request: `{"params": {"tab_id_filter": "0"}}`. A non-zero
-`tab_id_filter` restricts the stream to events for that tab.
-
-**M0 status:** stubbed. The server replies `{"ok": true, "result":
-{}}` and never sends event envelopes on the connection. This is
-intentional — `roostctl` does not need events for any current
-subcommand, and clients that *do* want events will surface as
-follow-ups against a working stub.
-
-Response: `{}`.
+**Not implemented.** The op exists on the wire but the server
+rejects every call with `{"ok": false, "error": {"code":
+"not-implemented", "message": "events.subscribe is not yet
+implemented"}}` (`ops::EVENTS_SUBSCRIBE` in
+`crates/roost-engine/src/ipc.rs`) rather than a false ACK — a client
+that treated the reply as "subscribed" would wait forever, since no
+event is ever pushed on the connection today. Callers that want
+current state should poll `tab.list` / `project.list` /
+`tab.dump` instead.
+
+Request shape as designed: `{"params": {"tab_id_filter": "0"}}`. A
+non-zero `tab_id_filter` would restrict the stream to events for
+that tab.
+
+**Forward note (HS-1):** push delivery lands with `roost-session`
+(the host-sessions daemon), delivered as atomic `EventBatch`es —
+`{"revision": <u64>, "events": [<EventEnvelope>, ...]}` — rather than
+one envelope per line. Batching every envelope that shares a
+`revision` lets a client detect loss with a simple gap check ("did I
+skip a revision?") instead of reconstructing individual dropped
+events; on a gap it re-pulls `tab.list` / `project.list`. Both
+`EventBatch` and `EventEnvelope` are already defined in
+`crates/roost-ipc/src/messages.rs` (landed ahead of the push
+implementation) — see [Events](#events) below for the envelope
+catalog they will carry.
 
 ## Events
 
-Server-push only. Each is a line of the form `{"event": "<name>", "data":
-{...}}`. The set below is the exhaustive list; no other event names are
-emitted.
+Server-push only, and **not delivered yet** — see
+[`events.subscribe`](#eventssubscribe). Each event is documented here
+in the envelope shape it will be pushed in once HS-1 implements
+delivery: a line of the form `{"event": "<name>", "data": {...}}`
+inside an `EventBatch`. The set below is the exhaustive list of event
+*types* the workspace already models; no other event names exist.
 
 * `tab.opened` — `{"tab": <Tab>}`.
 * `tab.closed` — `{"tab_id": "<id>"}`.
@@ -1069,7 +1090,9 @@ makes them unnecessary:
 * `ReportOsc`. OSC sequences are parsed in the UI; the UI updates
   its own state directly. There is nobody to round-trip to.
 * `WatchEvents` (legacy event stream RPC) is replaced by the
-  `events.subscribe` op + push envelopes on the same connection.
+  `events.subscribe` op + push envelopes on the same connection —
+  designed, wire-typed (`EventEnvelope` / `EventBatch`), but not
+  implemented yet; see [`events.subscribe`](#eventssubscribe).
 
 Schema-only fields that survive but rename:
 

docs/reference/paths.md

@@ -2,13 +2,14 @@
 
 Roost resolves all of its filesystem state once at startup. Other components read the paths from this resolution; nothing should derive its own.
 
-There are three bundle profiles — `Mac`, `Linux`, and `Iced` (slugs `mac`, `linux`, `iced`) — and each running UI resolves exactly one of them. There is no shared daemon; the profile a UI resolves determines the socket `roostctl` dials. The Rust definition lives in `crates/roost-ipc/src/paths.rs`; the Swift companion is `mac/Sources/Roost/BundleProfile.swift`. On macOS the two implementations are tested in lockstep.
+There are three UI bundle profiles — `Mac`, `Linux`, and `Iced` (slugs `mac`, `linux`, `iced`) — and each running UI resolves exactly one of them. There is no shared daemon; the profile a UI resolves determines the socket `roostctl` dials. A fourth profile, `Session`, exists in the same enum for the future `roost-session` daemon (HS-1) but is reserved: nothing launches it yet, and it is not a legal `roostctl` target or `ROOST_BUNDLE_PROFILE` value today (see [Session profile (reserved)](#session-profile-reserved) below). The Rust definition lives in `crates/roost-ipc/src/paths.rs`; the Swift companion is `mac/Sources/Roost/BundleProfile.swift`. On macOS the two implementations are tested in lockstep.
 
 | Profile | Who resolves it | `app_label` | `app_id` |
 |---|---|---|---|
 | `Mac`   | the Swift `Roost.app` | `Roost` | `ai.stridelabs.Roost` |
 | `Linux` | the packaged Linux UI (`/usr/bin/roost`) | `Roost-linux` | `ai.stridelabs.Roost` on Linux; `ai.stridelabs.Roost.linux` on macOS |
 | `Iced`  | a dev build of `roost-iced`, and the experimental macOS `Roost-Iced.app` | `Roost-iced` | `ai.stridelabs.Roost.iced` |
+| `Session` (reserved) | nobody yet — HS-1's `roost-session` daemon | `RoostSession` (`RoostSessionDev` in debug builds) | `ai.stridelabs.Roost.session` |
 
 `app_label` is fixed per profile on every platform — it is the string `identify` and `roostctl doctor` report, and on macOS it is also the directory component of the profile's paths. `app_id` is the only field that resolves per platform: on Linux the `Linux` profile shares `ai.stridelabs.Roost` with the `Mac` profile, which can never run there and already shares that platform's path namespace; on macOS every profile stays independently resolvable (so their paths and identities can never collide), even though nothing ships or launches the `Linux` one there.
 
@@ -23,7 +24,7 @@ The profile defaults to:
 | `roost-iced` (dev build, any platform; macOS `Roost-Iced.app`) | `Iced` | `ROOST_BUNDLE_PROFILE=mac` / `=linux` to dial another profile's namespace |
 | `roostctl` (binary from the `roost-cli` crate) | auto-detect | `ROOST_BUNDLE_PROFILE` / `--socket` / `ROOST_SOCKET` / `--target {mac,linux,iced}` |
 
-The two sides treat an **unrecognized** `ROOST_BUNDLE_PROFILE` value differently, on purpose. A UI logs a warning and falls back to its compiled-in default rather than refusing to launch; `roostctl` hard-errors with `unknown ROOST_BUNDLE_PROFILE value … (expected mac, linux, or iced)`. A stale `ROOST_BUNDLE_PROFILE=gtk` left over from an older install therefore starts the UI on its normal profile (with a warning in the log) but stops the CLI outright.
+The two sides treat an **unrecognized** `ROOST_BUNDLE_PROFILE` value differently, on purpose. A UI logs a warning and falls back to its compiled-in default rather than refusing to launch; `roostctl` hard-errors with `unknown ROOST_BUNDLE_PROFILE value … (expected mac, linux, or iced)`. A stale `ROOST_BUNDLE_PROFILE=gtk` left over from an older install therefore starts the UI on its normal profile (with a warning in the log) but stops the CLI outright. `session` gets the same `roostctl` rejection today even though it names a real profile kind internally — see [Session profile (reserved)](#session-profile-reserved) — because HS-1 hasn't defined how a session gets addressed yet.
 
 ## File locations
 
@@ -98,6 +99,22 @@ keep launching.
 
 The directories are created at first launch with mode `0700`.
 
+### Session profile (reserved)
+
+`Session` resolves paths the same way the three UI profiles do, but
+nothing launches it yet — it is reserved for the future headless
+`roost-session` daemon (HS-1). It is **not** a `roostctl` target and
+**not** a legal `ROOST_BUNDLE_PROFILE` value today; `roostctl --target
+session` and `ROOST_BUNDLE_PROFILE=session` are both rejected — see
+the `ROOST_BUNDLE_PROFILE` discussion above. Debug
+builds get their own `-dev`/`Dev`-suffixed directories so a dev
+session can never collide with a real one.
+
+| Platform | Socket | State | Logs |
+|---|---|---|---|
+| macOS | `~/Library/Caches/RoostSession/roost.sock` (`RoostSessionDev` in debug builds) | `~/Library/Application Support/RoostSession/` | `~/Library/Logs/RoostSession/` |
+| Linux | `$XDG_RUNTIME_DIR/roost-session/roost.sock`, falling back to `/tmp/roost-session-<uid>/roost.sock` (`roost-session-dev` in debug builds) | `$XDG_DATA_HOME/roost-session/` | `$XDG_STATE_HOME/roost-session/` |
+
 ### Two single-instance locks
 
 A running UI holds **two** flocks, because the two things a single