docs(spec): engine seam — carry herdr sessions, not only tmux - #109
Conversation
Investigation and design for an Engine seam, so `mir up --engine herdr` can work without pretending. Doc only; no production code. Part 1 maps the eight tmux couplings on the agent side with file:line — launch/--shell, the FrameWindows v2 snapshot, the ten-verb control allow-list, R3's hook push, D4's grouped sessions, G1's mirror and rw guests, doctor's checks, and every FrameWindows consumer — and states each one's capability without naming a multiplexer. Part 2 reports herdr 0.8.2 as measured in a contained sandbox, not as read: two clients share one focus (a second viewer's tab and workspace switches dragged the first viewer's screen), `terminal session observe` is a genuinely confined output-only pane stream (injected input, resize and scroll all had zero effect; a marker printed in another pane never reached it), `events.subscribe` pushes layout and agent-state changes with no hooks to install, and a small viewport is a crop rather than a reflow whenever another client owns the geometry. Part 3 specifies the Engine interface, a per-engine capability table, and the refusals that keep degradation visible — including serving one interactive attach at a time on an engine without per-attach views. Part 4 is the strategic read, including the risk that herdr ships its own remote layer. Closes #107 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KeiotDVE94wEzvc7wcvm1y
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9b43c0949d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Order E1 → E2 → E3 → E4 → E5 → E6 → E7 → E8. E1 is pure refactor and must | ||
| land alone. E5 gates every later slice, because until the refusal exists a | ||
| herdr machine can be corrupted by a second viewer. |
There was a problem hiding this comment.
Reorder the slices or keep the herdr engine inaccessible until E5 lands. In the specified order, E3 makes --engine herdr launchable and E4 adds focus-changing controls, while the second-attach refusal is deferred to E5; if these PR-sized slices are deployed independently, two Miranda clients can therefore share the server-global focus and disturb the first session—the exact corruption this paragraph says E5 prevents.
Useful? React with 👍 / 👎.
| - **Config isolation:** set `HERDR_SOCKET_PATH` explicitly under the Miranda | ||
| state dir rather than inheriting `$HOME/.config/herdr` — it avoids the | ||
| `sun_path` overflow measured in §2.0 and keeps Miranda's server out of the | ||
| user's own herdr session. |
There was a problem hiding this comment.
Do not unconditionally move HERDR_SOCKET_PATH into Miranda's state directory for the advertised existing-setup flow. The document establishes that the socket selects the herdr server/session, so this isolation starts or connects to a separate server with none of the user's existing workspaces, panes, or running agents; mir up --engine herdr would create a parallel empty setup rather than carry the session the user already has. Make isolation opt-in or provide an explicit way to select the existing socket.
Useful? React with 👍 / 👎.
| 3. **The refusal.** A capability a feature needs and the engine lacks is an | ||
| error at the point of use with the engine named in it, never a quiet | ||
| no-op. `mir share --write` on an engine without `GuestWrite` says so and | ||
| exits non-zero. `runControl` refuses a view verb the engine cannot scope, | ||
| and the frame is answered with an error the strip renders. |
There was a problem hiding this comment.
Specify an agent-to-client response and its web handling before requiring the strip to render these errors. The current protocol makes FrameControl client-to-agent only (go/internal/noise/frame.go), RunAgentSession drops the result after dispatch, and the proposed Engine.Control returns only a local Go error; no defined frame carries that error back to web/src/app.js. Consequently, an unsupported herdr view verb would still look like a dead button rather than the promised visible refusal.
Useful? React with 👍 / 👎.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
1 participant
Closes #107
Investigation and design spec for an
Engineseam, somir up --engine herdrcan work without pretending. Doc only — no production code changed.cd go && go test ./...andcd web && npm testboth green (167 web tests pass afternpm ciin a fresh worktree).Part 1 — what is coupled
Eight tmux couplings on the agent side, each cited with file:line and each restated as a capability that does not name a multiplexer: launch/
--shell, the FrameWindows v2 snapshot, the ten-verb control allow-list, R3's hook push, D4's grouped sessions, G1's mirror and rw guests,mir doctor, and every FrameWindows consumer ingo/andweb/.Two of them are the real gates:
isDefaultTmuxLaunchis byte-exact argv equality against{"tmux","new","-A","-s","main"}, andsessionFromLaunchis the one predicate that turns the snapshot, the push, and the control channel on or off together.Part 2 — herdr, measured
herdr 0.8.2, installed into a scratch directory with
HERDR_INSTALL_DIRand run under a throwawayHOME. The machine's own herdr config was never opened; the sandbox server was stopped and its state removed. Claims come from experiments, not from the docs:next_tab; A's own byte stream then contained tab 2's marker, and replaying A's capture shows A rendering tab 2. Repeated with workspaces, same result. There is no grouped-session analogue — named sessions are separate servers. D4 is unsupported.terminal session observeis genuinely confined. Injectedterminal.input,terminal.resizeandterminal.scrollall had measurably zero effect (0 occurrences of the injected text in the pane). A secret marker printed in another pane while the observer ran: 0 hits. Output printed in its own pane after focus moved away: 2 hits. This is a better read-only primitive than G1'scapture-pane+pipe-paneFIFO.events.subscribepushes layout, tab, pane andagent_statuschanges over the socket, replaying current state on subscribe. R3's 22 global hooks +wait-for+ 1 s poll collapse to one open socket.§2.7 lists what was not verified — Linux, real agent detection, reconnect under loss, id stability across restart.
Part 3 — the seam
An
Engineinterface with seven methods plus aCapsstruct, a per-engine capability table (supported / degraded / unsupported for tmux and herdr), and three enforcement points so nothing degrades quietly:mir doctorreports capabilities,mir upprints what it gives up, and a missing capability is an error naming the engine.One hard refusal: on an engine without per-attach views, Miranda serves one interactive attach at a time. Letting two viewers fight is the bug D4 was written to kill.
FrameWindows stays one wire format — the tmux-shaped ids move behind the engine,
a/bbecome optional, and agent state arrives as one optionalstfield that cannot break the v2 shape.Eight PR-sized slices with acceptance criteria (E1 is a pure refactor that must land alone; E5, the refusal, gates everything after it), plus an explicit out-of-scope list.
Part 4 — the strategic note
What Miranda gains, four things it must not promise, and the honest risk: herdr already ships
--remoteover SSH, a client/server split and a versioned protocol — every piece of a remote layer except the relay and the identity model.Five open questions for review at the end of the spec.
🤖 Generated with Claude Code
https://claude.ai/code/session_01KeiotDVE94wEzvc7wcvm1y
Note
Low Risk
Documentation-only change; no runtime, auth, or data-path behavior is modified.
Overview
Adds issue #107 design spec (
docs/superpowers/specs/2026-08-31-engine-seam-herdr-design.md) — investigation and architecture only, no implementation.The doc maps eight tmux-specific agent couplings (launch, FrameWindows snapshot, control RPC, R3 hooks, D4 grouped sessions, G1 guests,
mir doctor, consumers) to engine-neutral capabilities, with file:line citations into today’s code.It documents herdr 0.8.2 sandbox experiments (shared server focus → D4 unsupported; confined
terminal session observe;events.subscribepush; viewport crop vs reflow; heuristic agent state) and gaps left unverified.It specifies a future
Engineinterface +Caps, a tmux vs herdr capability matrix, no silent degradation (doctor, startup/HELLO, point-of-use errors), single interactive attach whenPerAttachViewis false,--engineselection/bootstrap rules, unchanged FrameWindows v2 with optionalst, and E1–E8 delivery slices plus strategic risks and five review questions.Reviewed by Cursor Bugbot for commit 9b43c09. Bugbot is set up for automated code reviews on this repo. Configure here.