feat: add terminal session control stream

3 files changed, 20 insertions, 0 deletions

diff --git a/docs/next/CHANGELOG.md b/docs/next/CHANGELOG.md
index e5a14798..0ae77de0 100644
--- a/docs/next/CHANGELOG.md
+++ b/docs/next/CHANGELOG.md
@@ -6,6 +6,7 @@
 - Added `session.snapshot` to bootstrap client runtime state in one socket API response before subscribing to events.
 - Added `herdr api schema` to inspect the bundled socket API schema, with `--json` for the full JSON Schema document and `--output PATH` for file output.
 - Added `herdr terminal session observe` for read-only live ANSI terminal streams that bridge processes can consume as newline-delimited JSON.
+- Added `herdr terminal session control` for bridge processes that need live ANSI frames plus input, resize, scroll, release, and takeover authority.
 
 ### Changed
 - Bumped the client/server protocol version to 15 for socket API placement mutation event and response compatibility.
diff --git a/docs/next/website/src/content/docs/cli-reference.mdx b/docs/next/website/src/content/docs/cli-reference.mdx
index d3f2f9c0..d4708df6 100644
--- a/docs/next/website/src/content/docs/cli-reference.mdx
+++ b/docs/next/website/src/content/docs/cli-reference.mdx
@@ -234,12 +234,19 @@ Use `pane send-text`, `pane send-keys`, `pane run`, and `terminal attach` for or
 
 ```bash
 herdr terminal attach <terminal_id> [--takeover]
+herdr terminal session control <target> [--takeover] [--cols N] [--rows N]
 herdr terminal session observe <target> [--cols N] [--rows N]
 herdr terminal title set <title>
 herdr terminal title clear
 ```
 
 Detach from direct attach with `ctrl+b q`. Send literal `ctrl+b` with `ctrl+b ctrl+b`.
+`terminal session control` opens a writable live terminal stream for a pane,
+terminal, or agent target. It prints the same newline-delimited
+`terminal.frame` and `terminal.closed` records as observe mode. It reads
+newline-delimited JSON commands on stdin: `terminal.input`, `terminal.resize`,
+`terminal.scroll`, and `terminal.release`. One controller can own a terminal at
+a time; use `--takeover` to replace it.
 `terminal session observe` opens a read-only live terminal stream for a pane,
 terminal, or agent target. It prints newline-delimited JSON `terminal.frame`
 records with base64-encoded ANSI bytes, then a `terminal.closed` record when
diff --git a/docs/next/website/src/content/docs/persistence-remote.mdx b/docs/next/website/src/content/docs/persistence-remote.mdx
index 1ef31fee..0a5c7ff7 100644
--- a/docs/next/website/src/content/docs/persistence-remote.mdx
+++ b/docs/next/website/src/content/docs/persistence-remote.mdx
@@ -133,6 +133,18 @@ bytes, then a `terminal.closed` record when the server closes the stream.
 Multiple observers can watch the same terminal without taking input, resize,
 scroll, or takeover ownership.
 
+For an interactive bridge, use a writable terminal session controller:
+
+```bash
+herdr terminal session control w1:p1 --takeover --cols 120 --rows 40
+```
+
+Control mode prints the same newline-delimited frame records and reads
+newline-delimited JSON commands on stdin. `terminal.input` sends text or
+base64 bytes, `terminal.resize` changes the controller viewport,
+`terminal.scroll` scrolls the attached viewport, and `terminal.release` closes
+the controller. Only one controller owns input and resize at a time.
+
 ## Single-process escape hatch
 
 Use `--no-session` to run Herdr without the background server/client split: