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
Related systems
Agent workspaces sit at the boundary between provider behavior, hooks, workspace lifecycle, remote execution, and user-facing conversation state.
- Agent integrations and hooks explains provider detection, hook setup, and status normalization.
- Agent Protocol Client sessions explains protocol-backed provider sessions.
- Workspace and worktree lifecycle explains workspace creation, activation, sleep, and cleanup.
- AI Vault sessions explains transcript discovery, history, previews, and explicit provider resumes.
- Native agent conversations explains the user-facing conversation model.
- Automation services explains non-interactive launches that use the same workspace and session boundaries.
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
| Trigger | Consequence | Guard |
|---|---|---|
| A session omits host, WSL, workspace, or account scope | A local, remote, or different-account conversation can collide with another session | Bind the full execution scope to the durable record and status identity |
| A retry changes the operation payload but keeps the old operation ID | The host can refuse the request or replay the wrong result | Compare the durable payload fingerprint before applying effects |
| A stale runtime fence writes after a new owner starts | An old process can change the replacement run | Require the expected fence and current owner authority |
| A launch route is recomputed after workspace creation | Prompt delivery can use a different surface than the one shown to the user | Carry one settled launch plan through all stages |
| A prompt receipt claims delivery before a journal commit or terminal handoff | A retry can be skipped or can duplicate a turn | Report only outcomes supported by delivery evidence |
| A provider handle is resumed under the wrong account or workspace | The conversation is unavailable or crosses an account boundary | Validate provider, scope, handle chain, and account before resume |
| A provider process exits while its child tree is unproven | Orca can release ownership while provider work remains live | Keep the result uncertain until tree death is proven |
| A current request marker belongs to an older epoch or owner | A stale approval or question can change the active conversation | Clear request state when ownership or epoch changes |
| A live batch is applied without its cursor or revision rules | Replayed data can reorder rows or revive removed work | Apply batches by epoch and cursor, then merge by row revision |
| A reconnect treats retained content as new activity | Old text can appear as fresh work and reset status timing | Resume from the last cursor and preserve evidence age |
| A queued send is hidden after a rejected handoff | The user loses the only retry or edit action | Keep returned and rejected queue cards visible until resolved |
| An optimistic message is treated as a recorded message | The transcript can claim delivery that the provider never received | Replace the echo only after journal or provider evidence |
| A child row is used to derive root status | Finished or background work can keep the parent working forever | Scope root status to the current root turn and child lifecycle |
| Session opening falls back after an uncertain host result | One user action can open or create two surfaces | Fall back only on a definitive unsupported response |
| A saved PTY or remote session ID is treated as proof of liveness | The UI claims a dead process is still running | Use the ID as a reattach hint and verify runtime evidence |
| Cleanup accepts a late event from a removed pane or workspace | Old work can repopulate a closed session | Enforce workspace and process identity fences |
Key files
| File | Why to read it |
|---|---|
| src/…/agent-session-record.ts | Defines durable session scope, provider handles, account binding, conversation naming, and ownership state. |
| src/…/agent-session-wire.ts | Defines the shared history, live subscription, status, mutation, and launch-facing contracts. |
| src/…/structured-agent-session-mutation.ts | Shows how durable operation identity and request fingerprints prevent duplicate effects. |
| src/…/agent-launch-executor.ts | Shows the common launch sequence from target resolution to surface publication. |
| src/…/agent-launch-prompt-delivery.ts | Shows how structured and terminal prompt outcomes are proved and reported. |
| src/…/acp-structured-handshake.ts | Shows structured provider session creation, resume, and history replay. |
| src/…/acp-structured-session-adapter.ts | Connects provider acquisition, controls, child work, and cleanup. |
| src/…/structured-agent-session-projection.ts | Defines the transcript and status projections used by native chat and session lists. |
| src/…/structured-agent-session-message-projection.ts | Shows how journal rows, submissions, queued work, and optimistic echoes become transcript messages. |
| src/…/structured-agent-session-live-read.ts | Shows history hydration, live subscription, contact loss, and cursor-based reconnect. |
| src/…/structured-agent-session-reducer.ts | Shows how snapshots, batches, resets, revisions, and queued state become client session state. |
| src/…/open-structured-agent-session.ts | Shows how history and notifications resolve to an existing tab, native chat, or terminal surface. |
| src/…/structured-agent-session-composer.ts | Shows which user commands act on the session and which become provider input. |
| src/…/structured-agent-session-queued-cards.ts | Shows how queued and returned messages remain visible and actionable. |
| src/…/server-status-update.ts | Shows how local and remote observations become normalized status. |
| src/…/server-cleanup.ts | Shows how status is dropped while provider resume identity and authority fences are preserved. |
| src/…/remote-workspace-session-projection.ts | Shows how remote workspace state is mirrored without moving local presentation state. |