[Feature]: Integrate stock Herdr as an Orca terminal multiplexer

[rudironsoni]

Status

This issue is the only home for the Herdr integration spec and plan. Older mapping text (one Herdr session per Orca project, one Herdr workspace per Orca worktree, no second Herdr UI) is obsolete.

Implementation PR: #10384

Goal

Add stock Herdr as another Orca terminal multiplexer option. Prefer the socket API. Use the CLI only to start a session, read the schema, or reach a host with no socket.

Users must be able to use the same terminals from Orca and from herdr --session orca in another emulator (for example Ghostty).

Runtime ownership and mapping

• One shared Herdr session named orca. A per-project session override is still allowed.
• One Herdr workspace per Orca project (the project repo root).
• Each Orca workspace opens as a Herdr worktree under that project workspace.
• Non-git folder workspaces cannot use worktree.open. They fall back to workspace.create and still carry an orca_binding token.
• One Herdr tab per Orca terminal tab.
• One Herdr pane per Orca pane leaf.

Orca owns project, workspace, tab, pane, and leaf identity. Herdr owns shell processes, scrollback, and durable runtime state. Socket events must converge both UIs.

Stock Herdr is the product path. The in-app daemon is an explicit fallback only. Do not grow the daemon until stock mapping and dual attach work.

Required behavior

• A user can select Herdr globally, per project, or per host.
• Default Herdr runtime is stock from PATH (or an explicit custom binary). Built-in daemon stays available as a fallback.
• Orca starts or attaches to herdr --session orca and talks protocol 19 over the session socket.
• Creating, closing, renaming, focusing, splitting, and resizing Orca surfaces updates the mapped Herdr resources without duplicates.
• Creating, closing, renaming, focusing, splitting, and resizing in the stock Herdr TUI updates the mapped Orca surfaces without duplicates.
• Typing in either UI updates the other. Orca must not steal Herdr TUI focus on attach.
• Closing Orca does not stop the Herdr session. Explicit close of a pane, tab, or workspace closes the intended Herdr resource.
• Restarting Orca or Herdr converges to the same project, worktree, tab, pane, and split topology.
• Local, WSL, and SSH-backed projects use the same ownership and mapping. WSL/SSH may use CLI or a socket relay, but the mapping stays the same.
• The integration works with an unmodified upstream Herdr binary. Pinned stock version lives in config/herdr-version.json.

Plan (do in this order)

1. Keep this issue current. Point PR feat(terminal): integrate stock Herdr runtime #10384 at this model. Do not keep plans only in .opencode/plans.
2. Default herdrRuntimeSource to stock. Route the local transport from the resolved Herdr backend and the explicit runtime source. Keep daemon behind the Built-in daemon setting.
3. Resolve the project repo root. Pass repoPath. Call worktree.open for linked git checkouts (cwd = repo root, path = workspace path). Use workspace.create for the project root and for non-git folders. Reconcile every workspace of the project, not only the spawn target. Key runtime graphs by session and project.
4. Dual attach: no pane.focus on attach. Use pane.send_input for keystrokes. On Herdr structural events, update Orca tabs and layouts. Orca close still closes Herdr. A close that starts in Herdr retires the Orca leaf or tab. Do not take exclusive terminal session control if that blocks the Ghostty client.
5. Later: live frames instead of pane.read polling if the pinned protocol allows a non-exclusive observe path. Orca agent launch through agent.start / agent.prompt.

Done when

• herdr --session orca in Ghostty shows the same project workspace, worktrees, tabs, and panes Orca created.
• Typing in either UI updates the other.
• A second Orca workspace in the same project appears as a Herdr worktree, not a second unbound workspace.
• This issue describes the live model. The PR body matches it.

Acceptance tests

• Native stock path has live integration coverage against the pinned Herdr binary.
• Electron e2e covers open, type, and reattach. Stock is the product gate when the binary is present. Daemon e2e may remain as a fallback suite.
• WSL and SSH command construction has automated coverage.
• Restarting Herdr itself restores the same shells, scrollback, and layout without duplicates.

[rudironsoni]

Progress on feat/herdr-stock-runtime (this issue is the spec):

Shipped:

• Spec rewrite here and PR feat(terminal): integrate stock Herdr runtime #10384 body now match this model.
• Removed .opencode/plans so this issue is the only plan home.
• Default herdrRuntimeSource is stock. Built-in daemon is an explicit fallback. Daemon e2e stays on that fallback.
• Production now sets repoPath from the git repo root. Linked checkouts call worktree.open. The project root and folder repos use workspace.create.
• Reconcile graphs include sibling worktrees for the project. Runtime graphs are keyed by session and project so a shared orca session no longer last-write-wins.
• Stock attach no longer calls pane.focus. Keystrokes use pane.send_input. A Herdr pane that disappears retires the Orca binding.

Still open from this issue:

• Import tabs/splits created in the Herdr TUI into Orca layouts (closes now propagate; creates do not yet).
• Live frames instead of pane.read polling.
• Orca agent launch through agent.start / agent.prompt.

[rudironsoni]

Pushed to feat/herdr-stock-runtime (33916d65ef).

Landed since the last comment:

• Herdr-created tabs and splits are claimed, persisted, and sent to the renderer as ui:createTerminal (new tab or split-from-leaf).
• Stock I/O uses herdr terminal session observe for frames and pane.send_input for keys, so Ghostty can stay attached.
• Orca agent launch for overlapping kinds (claude, codex, grok, …) calls agent.start instead of writing a shell command.

Commits:

• f74a194e29 feat(herdr): default stock runtime and map project worktrees
• 33916d65ef feat(herdr): import TUI surfaces, observe frames, and start agents

[rudironsoni]

Pushed 59b78332ec to feat/herdr-stock-runtime.

Herdr TUI changes now update Orca:

• rename → ui:renameTerminal
• focus → ui:focusTerminal
• close → ui:closeTerminal
• split resize → ui:applyTerminalLayout

Also deleted the unused duplicate agent modules.

Still not automated here: stock Ghostty dual-attach e2e, and a live Herdr process-restart suite.