[idea] First-class runtime integration with third-party ADEs

[rudironsoni]

idea / problem

I use Orca as my project and worktree UI and want Herdr to be its terminal runtime, with no separate multiplexer surface to manage. Today Orca owns terminal lifetime, so quitting it ends the shells instead of detaching from a persistent Herdr session.

requested change

Support a stable one-to-one mapping: one named Herdr session per Orca project, one workspace per worktree, one tab per Orca terminal tab, and one pane per Orca pane. Quitting Orca should detach while shells and scrollback remain alive; reopening should reconstruct and reattach the same graph. Local and SSH-backed projects should behave the same way. This likely needs durable caller-owned resource identities, race-free snapshot/event reconciliation, and non-interactive terminal control. I would like to contribute the Herdr-side pieces if this direction fits the project, but I will not open a PR without maintainer approval. Corresponding Orca proposal: stablyai/orca#9033

Why

I want Orca to support Herdr as an optional, first-class terminal runtime, without nesting a Herdr UI inside an Orca terminal.

The goal is to preserve Orca's existing terminal surfaces while Herdr owns the durable terminal processes and session lifecycle. This provides detach, reconnect, and application-restart persistence without changing how users interact with Orca.

The intended mapping is:

• One Herdr session per Orca project.
• One Herdr workspace per Git worktree.
• One Herdr tab per Orca terminal tab.
• One Herdr pane per Orca terminal pane.

What I implemented

The Herdr side is available on rudironsoni:feat/orca-integration, coordinated with Orca PR #9440.

The branch extends the socket API with the primitives needed for an external application to manage this mapping safely:

• Stable external references for workspaces, tabs, and panes.
• Explicit workspace.bind, tab.bind, and pane.bind operations.
• Ownership-scoped identities, so different integrations can use the same external ID without collisions.
• Idempotent adoption and conflict detection.
• Snapshot capability negotiation.
• Resumable event consumption for reconnecting clients.
• Terminal input, resize, history, clear, and close operations.
• Controller takeover for reconnecting Orca instances.
• Generated socket API schema updates and invariant tests.

The external reference is a composite (owner, id) identity. Orca uses its own durable entity IDs, while Herdr remains responsible for its native resource IDs and lifecycle.

How it works

When Orca opens a project, it connects to Herdr through the socket API and negotiates the required capabilities. Orca then reconciles its persisted project graph against Herdr's current snapshot.

For each Orca surface:

1. Orca looks for a Herdr resource already bound to its external identity.
2. If found, Orca adopts it and reconnects the terminal surface.
3. If absent, Orca creates the Herdr resource and binds it.
4. If the identity is already bound incompatibly, the API returns an explicit conflict instead of silently reusing or replacing another resource.

Terminal rendering remains inside Orca. Input, resize events, history recovery, and lifecycle commands pass through the Herdr socket API. Closing or restarting Orca does not kill the Herdr session, so reopening the project reconstructs the same workspaces, tabs, and panes.

The Orca integration is opt-in. Users can keep the existing Orca PTY runtime globally or per project, and choose a managed, system-installed, or custom Herdr binary. Existing live Orca PTYs are not silently migrated.

Compatibility and validation

The API additions are capability-negotiated, so clients can detect support before using the integration. Existing Herdr behavior remains the default, and the new external identity fields are optional for normal Herdr usage.

The branch includes tests for binding, idempotency, ownership isolation, duplicate-reference rejection, capability snapshots, protocol/schema consistency, and state invariants. cargo build --locked and the targeted integration tests pass.

If this direction fits Herdr, could you convert this discussion into an accepted issue and approve the contribution path with /approve @rudironsoni? I'll open the upstream PR after approval.

[rudironsoni]

@ogulcancelik what do you think?