[ttmuse]

Summary

Replaces §10 of runtime/CLIENT-CONTRACT.md. (This PR previously specified a client-side-only Shepherd plane; that model has been withdrawn and the section rewritten — see "What changed" below.)

New §10 — Shared session and floor control — Shepherd as an outer layer (optional, proposed):

• One session, one PTY stream, two kinds of writer. The operator attaches (§4) and drives the terminal directly — native rendering at the client's own geometry, unmediated keystrokes. The agent CLI is the foreground program of that same session. Shepherd owns no second terminal; it acts as an outer layer (routines) that observes the session and submits messages to be typed into it.
• Session state (proposed runtime behaviour). The runtime tracks and reports working / idle / blocked plus human presence. idle must rest on a hard signal (e.g. an OSC status sequence); output quietness alone never establishes it.
• Floor arbitration (proposed runtime behaviour). Shepherd never writes to the PTY. It submits a message and requests the input floor; the runtime grants only when the session is idle, no human input is recent, and the foreground program is the agent CLI — never at a bare shell prompt. On grant the runtime performs one atomic write; the floor is revoked on turn start or the first human keystroke.
• Blocked is not idle. Dialogs are answered only under the dialog discipline (allow_once / deny_once, no "always allow"); free-form submission while blocked is refused.
• The operator is never gated. Floor control constrains the automation layer only; the attach stream is never throttled or refused. Every granted injection is audit-recorded (identity, routine, timestamp, message) and visible to attach clients.

What changed vs the previous draft of this PR

The earlier §10 kept the planes fully separate — Shepherd-owned panes, the runtime not a party, and a rule that the attach session must never be used as a side channel into a pane. Discussion concluded the better shape for the operator experience is a single shared session with the runtime arbitrating automation writes: separation is replaced by arbitration. Policy now binds Shepherd and routines at the system level, and stops binding — indeed never touches — the operator.

Relation to #77

Unchanged in scope: #77 is an RFC for workflow orchestration over the control plane. This remains one session shared by its operator and one outer-layer supervisor; no orchestration or control-plane semantics.

Companion

The Shepherd-side reference, openabdev/openab-shepherd#41 (docs/terminal-clients.md), documents the pane-owning model. If this shared-session model is adopted, a companion update on the Shepherd side will be needed; this PR does not change any Shepherd behaviour by itself.

Closes #97

Discussion

Discussion thread in the OpenAB Discord #openab-pty channel: https://discord.com/channels/1491295327620169908/1539248427634790451/1571180280939683940