Introducing a new way to review your PRs.

Read the announcement

stablyai / orca

Orca lets you run a fleet of bots with your own subscription (e.g. Claude Code, Grok, Agy, Codex). Available on desktop, mobile and remote runtime.

View on GitHub

34 documents · Updated Nov 20, 2026

docs / agent-workspaces

Agent workspaces and sessions

Orca gives coding-agent work a stable identity inside a local or remote workspace. It separates the workspace from the provider conversation, running process, observations, and user-facing surface so an engineer can start work, leave it, and return without creating a second conversation.

Workspace session model

An Orca session is the durable view of agent work in a folder workspace or Git worktree. It connects provider state to terminal and native-chat surfaces while allowing the process and presentation surface to change.

Workspace scope

An execution scope identifies where an agent runs. It includes the execution host, any WSL distribution, the workspace, the workspace kind, and the provider account home. Native, WSL, SSH, and other remote copies remain separate even when they use the same workspace name.

The same scope applies to the durable session and its status records. This prevents a local process from claiming a remote session and keeps one account or runtime from answering for another. A session keeps its provider identity even when the provider is not currently available.

References: src/…/agent-session-record.ts• L42-51 src/…/agent-session-record.ts• L108-149 src/…/agent-session-wire.ts• L199-273

Session identity

Orca keeps three identities apart because they have different lifetimes:

  • A surface identity names where the user sees or controls the work. A terminal pane or native-chat tab can move or reconnect without creating a new conversation.
  • A provider identity names the conversation that an agent can resume. It can be a session, thread, branch, or transcript locator. Provider resets and forks form a continuity chain rather than silently replacing the old run.
  • A run identity names one observed process incarnation. It prevents late events from an old process from changing the state of a replacement process.

One provider conversation can move to another surface, and one surface can later host another conversation. Child-agent output stays linked to its producer inside the same session timeline instead of creating another pane.

References: src/…/agent-session-record.ts• L66-105 src/…/agent-session-record.ts• L108-149 src/…/structured-agent-session-projection.ts• L75-151

Durable ownership

The durable session record binds provider identity to its execution scope and account home. It also records launch choices, the current owner, the conversation name, and operation state. The record can outlive a terminal tab, client, or provider process.

Only the current execution owner can create, resume, or write to a provider session. Mutating actions carry an operation identity, a request fingerprint, and an expected runtime fence. A retry can replay one saved result, while a changed request or stale owner is refused.

References: src/…/agent-session-record.ts• L80-151 src/…/structured-agent-session-mutation.ts• L22-85 src/…/agent-session-wire.ts• L300-321

Agent launch and resume

Orca treats a fresh launch, a surface attachment, and a provider resume as different actions. A launch creates provider state, attachment makes an existing structured session visible, and resume starts provider state that already exists.

Launch route

The shared launch path selects a structured native-chat surface or a terminal surface before provider startup. It uses an explicit caller choice when present. Otherwise it uses the user's default and checks the target workspace, execution host, agent support, and client capability.

The route is settled once and carried through workspace creation, surface creation, publication, and prompt delivery. A default chat preference can downgrade to a terminal when the host cannot support chat. An explicit chat request falls back only after Orca proves a definitive structured-session refusal. A new workspace keeps a recovery shell when cancellation or an uncertain surface result occurs so the workspace remains usable without starting a second agent.

Cancellation stops the launch at the next safe boundary before an agent exists. After a surface exists, Orca returns the created agent and reports the prompt outcome that it can prove rather than pretending the launch was undone.

This diagram shows how one launch becomes one selected surface while preserving the workspace after a partial launch.

flowchart LR
    A[Agent and workspace target] --> B[Resolve execution scope]
    B --> C[Choose chat or terminal route]
    C --> D[Create or resolve workspace]
    D --> E[Confirm support on executing host]
    E --> F[Create or reuse one surface]
    F --> G[Publish launch outcome]
    G --> H[Deliver initial prompt]
    D -. cancellation or uncertain result .-> R[Create recovery shell]

References: src/…/agent-launch-executor.ts• L55-190 src/…/agent-launch-mode.ts• L96-164 src/…/agent-launch-mode.ts• L166-253 src/…/startup-agent-worktree-create.ts• L21-69

Prompt delivery

The initial prompt follows the selected surface. Structured chat records the first submission before provider delivery. A terminal agent receives the prompt through its launch path when possible or through the host-owned terminal path when it must wait for an idle composer.

Prompt delivery can fail after the agent or session exists. Orca reports delivery separately from creation so a caller does not create a second workspace or conversation. A submission that was not proved remains pending or unknown until later evidence or an explicit retry.

References: src/…/agent-launch-prompt-delivery.ts• L35-117 src/…/structured-agent-session-send-mutation.ts• L14-99 src/…/structured-agent-session-message-projection.ts• L31-45

Provider resume

Resume uses provider metadata captured from a live, sleeping, or historical session. Orca validates the provider and workspace identity, then builds the provider-specific resume request in the owning workspace. Some providers use a session or thread ID. Others need the exact transcript file or a resume cursor.

A provider may reset or fork its conversation. Orca records that change as a new link in the provider handle chain so the session remains one user-visible history while its current resume target stays correct. A copied conversation remains in the selected account and provider store.

References: src/…/agent-session-record.ts• L108-149 src/…/agent-session-fork.ts• L1-120 src/…/acp-conversation-copy.ts• L26-149

Workspace trust

Before launch, Orca can prepare provider trust for the workspace on the host that will run the agent. Local, WSL, and SSH launches use different trust locations, and Orca avoids broad home or filesystem-root grants.

Orca records the exact trust entries it creates for providers that need cleanup. Workspace removal can delete only an unchanged entry created by Orca, so it does not remove a user's later choice.

References: src/…/agent-workspace-trust.ts• L15-109 src/…/execution-host-workspace-trust.ts• L20-35 src/…/agent-trust-ownership-ledger.ts• L7-31

Provider session adapters

Provider adapters turn provider-specific processes and protocols into the common Orca session contract. They start or reopen one provider conversation, translate provider events into journal and child-work evidence, expose provider options, and settle exit or delivery outcomes for the host.

Agent Protocol Client sessions

Agent Protocol Client sessions use a long-lived bidirectional protocol connection. Orca publishes the provider child before the handshake, then initializes the protocol and loads the requested session or starts a new one.

The adapter translates messages, reasoning, tools, plans, usage, prompts, forms, approvals, and child work into the common timeline. A broken connection closes journal input and stops the child. A proven process exit then publishes the final lifecycle result. An unproven tree remains an uncertain stop rather than a clean close.

References: src/…/acp-structured-acquire.ts• L34-47 src/…/acp-structured-handshake.ts• L54-106 src/…/acp-session-runtime.ts• L68-200 src/…/acp-dialect.ts• L94-170

Provider timeline

The provider timeline is the common record of a session's visible work. It keeps message ownership, tool state, diffs, failures, background tasks, subagents, context use, and provider frames tied to the correct turn even when events arrive late or out of order.

The session view reads this timeline as ordered history. It replaces revised rows in place, keeps submissions beside their journal rows, and does not let a child row describe the root agent's current turn.

References: src/…/acp-timeline-translator.ts• L40-73 src/…/acp-timeline-translator.ts• L163-272 src/…/structured-agent-session-history-state.ts• L28-123 src/…/structured-agent-session-live-turn.ts• L23-87

Requests and controls

Provider requests become durable approval or question cards when they need a person. Orca checks that a request belongs to the active session and keeps current requests separate from paged history, so a reconnect does not offer an old answer target.

The composer sends turns, stops active work, selects provider options, runs provider commands, and attaches workspace files or images. Commands owned by Orca act on the session without becoming provider messages. Other text follows the provider's normal turn path.

References: src/…/agent-session-current-requests.ts• L24-83 src/…/structured-agent-session-composer.ts• L84-113 src/…/structured-agent-session-composer.ts• L178-281 src/…/structured-agent-session-send-mutation.ts• L101-128

Turns and queued work

A turn is the unit of provider work that Orca shows as working, waiting for attention, or settled. A new send starts a turn when the session is idle. A send during active work can become a steer or a queued message, depending on the selected delivery mode.

Queued messages remain separate from the transcript until the host hands them to the provider. The user can see why a message waits, resume eligible work, edit supported drafts, or retry a returned message. A rejected handoff does not disappear as if it were delivered.

References: src/…/structured-agent-session-live-turn.ts• L89-212 src/…/structured-agent-session-queued-cards.ts• L39-73 src/…/structured-agent-session-queued-cards.ts• L107-179

Child work

Child work is work started inside a provider session without its own terminal pane. It can be a subagent, background task, workflow, command, or monitor. Orca keeps its parent, provider identity, lifecycle, outcome, and invocation identity so the work can appear in workspace status and native chat without inventing another session.

A missing child from an incomplete roster does not prove that it ended. Lost contact is shown as unverifiable. Settled child rows can remain visible for context while no longer keeping the parent session working.

References: src/…/acp-subagents.ts• L41-117 src/…/acp-background-task-timeline.ts• L13-57 src/…/agent-session-background-task-wire.ts• L1-95

Agent observation

Orca observes agent work through provider evidence, process evidence, structured-session projections, and terminal evidence. These sources describe the same work with different levels of certainty, so Orca records identity, authority, and freshness before it presents a state.

Observation channels

Managed integrations send rich events to the loopback hook server. Program Status Protocol, also called OSC 7501, sends state from the terminal stream for agents that support it. Structured sessions publish their state through the session host because they do not need hooks.

Hooks normally own the row. OSC 7501 can enrich or take over only under the provider-specific silence and turn rules. The status view combines hook rows with structured-session rows while filtering internal terminal rows that are not user sessions.

References: src/…/README.md• L3-27 src/…/README.md• L91-111 src/…/combined-agent-status-entries.ts• L17-59 src/…/agent-session-wire.ts• L199-273

Run status

A status run is one observed process incarnation. Its identity joins the run, pane, provider evidence, role, verdict, and execution scope. The verdict can be live, exited, or unverifiable. Unverifiable means Orca cannot prove an exit.

Structured-session status projects journal and provider evidence onto the same workspace vocabulary as hook and terminal status. It can report startup, working, attention, idle, or an uncertain outcome without treating a process exit as provider success.

References: src/…/agent-session-wire.ts• L199-273 src/…/structured-agent-session-projection.ts• L122-252 src/…/server-status-application.ts• L130-195 src/…/server-status-update.ts• L52-189

Remote observations

Local observations enter Orca directly. Remote observations travel through a relay and are checked at the receiving host before they become shared status. Both paths use the same status meaning, but the receiving authority and freshness rules prevent delayed remote data from replacing a newer run.

Identity-only provider rows can preserve a resume target without claiming that a process is working. A provider child or terminal event can later add live evidence when the owning runtime proves it.

References: src/…/server-status-update.ts• L125-186 src/…/server-remote-envelope-normalization.ts• L67-139 src/…/wsl-bridge-daemon-sessions.ts• L27-50

Session lifetime and continuity

The host keeps a durable session readable when no provider process is running. This lets Orca restore a conversation, preserve status and drafts, and start live provider work only when a send or explicit resume needs it.

Conversation lifetime

An open conversation is an access point to the durable session record and journal. Opening it restores readable history but does not start a provider child. A send, queued delivery, or explicit resume acquires live execution.

When the session is quiet, the host can stop the provider child and release its live handle. The durable record, journal, tab, status, and readers remain. The next send or resume creates a new provider run under the same session identity.

References: src/…/structured-agent-session-host.ts• L59-177 src/…/structured-agent-session-conversation-lifetime.ts• L98-160 src/…/agent-session-record.ts• L108-151

Restart recovery

Restart first restores durable records and readable journals. It does not start a provider child for every saved session. An owner that may still exist remains in recovery until process identity or host evidence proves that it stopped.

An unresolved submission is shown as unknown and is not sent again automatically. A continuation starts only after an explicit resume action. This protects against duplicate turns when a transport or host restart occurred after the provider may have accepted a send.

References: src/…/structured-agent-session-restart-restore.ts• L1-81 src/…/structured-agent-session-restart-resume-runner.ts• L57-139 src/…/structured-agent-session-message-projection.ts• L220-259

History and live continuity

Session history uses bounded pages with cursors. A live reader applies snapshots, batches, and resets to the current page. Revisions replace matching rows, removed rows are deleted, and older history is fetched without losing the live cursor.

When contact is lost, Orca keeps the last readable transcript and reconnects from the last applied cursor. A reset replaces the page when the journal has changed its epoch or the retained window is no longer valid. The reader does not mark stale content as new provider activity.

This diagram shows how a session view moves from stored history to live updates and then back through recovery without creating another session.

flowchart LR
    A[Read history page] --> B[Apply snapshot]
    B --> C[Subscribe from cursor]
    C --> D[Merge journal batches]
    D --> C
    C -. contact lost .-> E[Keep readable state]
    E --> F[Reconnect with cursor]
    F --> C
    F -. epoch or window reset .-> G[Replace page]
    G --> C

References: src/…/agent-session-wire.ts• L62-120 src/…/structured-agent-session-live-read.ts• L26-64 src/…/structured-agent-session-live-read.ts• L141-204 src/…/structured-agent-session-reducer.ts• L166-319

Workspace continuity

Workspace persistence restores the tab and pane model, active selection, editor and browser state, and remote connection hints. It does not treat a saved PTY ID as proof that a process still exists.

For a remote workspace, the executing host owns the workspace snapshot. Clients mirror tabs, pane layouts, active selection, shutdown activity, and remote session IDs while keeping local presentation details local. Revision checks prevent a stale mirror from replacing newer workspace state.

References: src/…/workspace-session-state-types.ts• L32-111 src/…/remote-workspace-types.ts• L1-50 src/…/remote-workspace-session-projection.ts• L32-205

Workspace sleep and cleanup

Workspace sleep pauses live resources for a workspace on the host that owns it while preserving enough session state to resume later. Wake requests remain ordered with sleep and delete operations, so a reopened pane or agent uses the existing session boundary.

Workspace cleanup removes agent status and workspace-owned resources only after the owning host and current workspace are known. It retains provider identity when the process ends so the user can resume, while removed worktrees and panes reject late events.

References: src/…/managed-workspace-operations.ts• L217-279 src/…/workspace-sleep.ts• L1-120 src/…/server-cleanup.ts• L21-61 src/…/server-cleanup.ts• L173-241

Agent session presentation

Orca presents an agent through terminal surfaces, native chat, workspace status rows, and session lists. The terminal is the direct process view. Native chat and status rows are projections of the durable session and its evidence.

Native chat transcript

Native chat turns the session journal into one readable thread. It combines user prompts, assistant output, reasoning, tool work, diffs, approvals, questions, turns, child agents, background tasks, and delivery state.

Turns describe activity and outcome rather than replacing the messages and tool work that produced them. Pending approvals and questions remain action surfaces. Child rows retain producer links so delegated work is visible without becoming a second session.

References: src/…/structured-agent-session-projection.ts• L75-119 src/…/structured-agent-session-message-projection.ts• L100-265 src/…/structured-agent-session-status-block.ts• L26-94

Session history and status

Session lists use a compact status summary instead of replaying every transcript row. The summary reports the latest prompt, working tool, assistant preview, turn outcome, pending attention, provider options, child work, and conversation name when the host can prove them.

The same session data drives the sidebar, native-chat header, and status rows. A child update can change a display without changing the root turn. A completion from an old fence or surface does not mark the current tab complete.

References: src/…/agent-session-wire.ts• L199-273 src/…/structured-agent-session-projection.ts• L154-252 src/…/structured-agent-session-live-turn.ts• L137-212

Session opening and tabs

Opening a session first checks for an existing tab, then refreshes known state, and finally reveals the session when needed. It accepts history, notification, or sender references and can return a terminal surface when no native-chat surface is available.

The open result distinguishes an opened chat, a terminal handle, a missing workspace, an unsupported host, an unreachable host, and a superseded request. This keeps a failed lookup from being mistaken for a provider failure or a new launch.

References: src/…/open-structured-agent-session.ts• L22-49 src/…/open-structured-agent-session.ts• L145-291 src/…/structured-agent-session-tab.ts• L7-25

User actions

The composer sends turns, stops active work, selects provider options, runs provider commands, and attaches workspace files or images. Its draft belongs to the session surface, so reconnects and surface changes do not move input to another session.

When a provider waits for approval or a question, chat replaces ordinary input with a durable action card. Queued follow-ups remain separate from the transcript until the host converts one into a submission.

References: src/…/structured-agent-session-composer.ts• L21-59 src/…/structured-agent-session-queued-cards.ts• L107-179 src/…/agent-session-current-requests.ts• L69-83

Agent workspaces sit at the boundary between provider behavior, hooks, workspace lifecycle, remote execution, and user-facing conversation state.

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep execution scope aligned across session records, provider accounts, provider handles, status rows, history reads, and remote routing.
  • Keep provider handle chains and account homes aligned with resume, fork, and conversation-copy behavior.
  • Keep operation fingerprints stable across client and host retries. A changed request must not replay an old effect.
  • Keep runtime fences aligned with owner acquisition, process evidence, mutation admission, and live status publication.
  • Keep one launch route fixed from mode selection through workspace creation, surface creation, publication, and prompt delivery.
  • Keep prompt receipts tied to journal or terminal evidence. An interrupted submit must remain unconfirmed.
  • Keep provider turn state separate from child-work state. A child update must not become a root completion.
  • Keep current request markers tied to the current session epoch and owner. A reconnect must not answer an old prompt.
  • Keep history cursors, journal epochs, row revisions, removals, and reset handling aligned across host and clients.
  • Keep queued-message cards aligned with submission handoff. A rejected handoff must remain visible and actionable.
  • Keep optimistic messages separate from recorded submissions until the host proves delivery.
  • Keep host status summaries aligned with the same root-turn, prompt, and outcome rules used by native chat.
  • Keep session opening fallbacks limited to proven unsupported responses. An uncertain result must not start a second session.
  • Keep workspace sleep and wake records bound to the owning host and workspace. A reopened pane must use the existing provider session.
  • Keep cleanup fences and process identity checks in place so removed workspaces reject late observations.

Important failure modes

TriggerConsequenceGuard
A session omits host, WSL, workspace, or account scopeA local, remote, or different-account conversation can collide with another sessionBind the full execution scope to the durable record and status identity
A retry changes the operation payload but keeps the old operation IDThe host can refuse the request or replay the wrong resultCompare the durable payload fingerprint before applying effects
A stale runtime fence writes after a new owner startsAn old process can change the replacement runRequire the expected fence and current owner authority
A launch route is recomputed after workspace creationPrompt delivery can use a different surface than the one shown to the userCarry one settled launch plan through all stages
A prompt receipt claims delivery before a journal commit or terminal handoffA retry can be skipped or can duplicate a turnReport only outcomes supported by delivery evidence
A provider handle is resumed under the wrong account or workspaceThe conversation is unavailable or crosses an account boundaryValidate provider, scope, handle chain, and account before resume
A provider process exits while its child tree is unprovenOrca can release ownership while provider work remains liveKeep the result uncertain until tree death is proven
A current request marker belongs to an older epoch or ownerA stale approval or question can change the active conversationClear request state when ownership or epoch changes
A live batch is applied without its cursor or revision rulesReplayed data can reorder rows or revive removed workApply batches by epoch and cursor, then merge by row revision
A reconnect treats retained content as new activityOld text can appear as fresh work and reset status timingResume from the last cursor and preserve evidence age
A queued send is hidden after a rejected handoffThe user loses the only retry or edit actionKeep returned and rejected queue cards visible until resolved
An optimistic message is treated as a recorded messageThe transcript can claim delivery that the provider never receivedReplace the echo only after journal or provider evidence
A child row is used to derive root statusFinished or background work can keep the parent working foreverScope root status to the current root turn and child lifecycle
Session opening falls back after an uncertain host resultOne user action can open or create two surfacesFall back only on a definitive unsupported response
A saved PTY or remote session ID is treated as proof of livenessThe UI claims a dead process is still runningUse the ID as a reattach hint and verify runtime evidence
Cleanup accepts a late event from a removed pane or workspaceOld work can repopulate a closed sessionEnforce workspace and process identity fences

Key files

FileWhy to read it
src/…/agent-session-record.tsDefines durable session scope, provider handles, account binding, conversation naming, and ownership state.
src/…/agent-session-wire.tsDefines the shared history, live subscription, status, mutation, and launch-facing contracts.
src/…/structured-agent-session-mutation.tsShows how durable operation identity and request fingerprints prevent duplicate effects.
src/…/agent-launch-executor.tsShows the common launch sequence from target resolution to surface publication.
src/…/agent-launch-prompt-delivery.tsShows how structured and terminal prompt outcomes are proved and reported.
src/…/acp-structured-handshake.tsShows structured provider session creation, resume, and history replay.
src/…/acp-structured-session-adapter.tsConnects provider acquisition, controls, child work, and cleanup.
src/…/structured-agent-session-projection.tsDefines the transcript and status projections used by native chat and session lists.
src/…/structured-agent-session-message-projection.tsShows how journal rows, submissions, queued work, and optimistic echoes become transcript messages.
src/…/structured-agent-session-live-read.tsShows history hydration, live subscription, contact loss, and cursor-based reconnect.
src/…/structured-agent-session-reducer.tsShows how snapshots, batches, resets, revisions, and queued state become client session state.
src/…/open-structured-agent-session.tsShows how history and notifications resolve to an existing tab, native chat, or terminal surface.
src/…/structured-agent-session-composer.tsShows which user commands act on the session and which become provider input.
src/…/structured-agent-session-queued-cards.tsShows how queued and returned messages remain visible and actionable.
src/…/server-status-update.tsShows how local and remote observations become normalized status.
src/…/server-cleanup.tsShows how status is dropped while provider resume identity and authority fences are preserved.
src/…/remote-workspace-session-projection.tsShows how remote workspace state is mirrored without moving local presentation state.