Execution protocol version 2 separates explicit useRoots and Workspace capture references from bounded mutationRoots for managed operations. The selected Workspace is captured by the process facade; callers may explicitly add other references. Sandbox reach never discovers or captures unrelated mounts. Hosts and clients reject a protocol version mismatch before dispatch; old persisted receipts retain their existing identity for recovery.
Docker inspection distinguishes partial creation from loss of an acknowledged container using its incarnation receipt. Leftover staging volumes do not turn a lost allocation into pending creation. Lost Workspace views remain unavailable and retain their unresolved ownership; repeated loss observations do not advance the catalog revision.
An Environment identifies an execution destination independently of a Session, Scope and Workspace. Harness owns the catalog in Agent Storage; native and remote resource owners implement providers.
Sessions persist an optional Environment ID independently of their Workspace ID. Creation, parent/child inheritance and forks select that identity without allocating compute. Composition can register one explicit default; the local preset selects native, while environment: false in either embedded runtime entry point omits it. Explicit null disables the default. Transcript imports clear execution authority. The versioned Session migration records the configured default without allocating, inherits parent selections and keeps unavailable imported Workspaces unbound.
Owner bindings select a logical Environment without allocating it. Environment.acquire persists an allocation intent before calling its provider and coalesces concurrent acquisition within the writing Runtime. The target includes the Environment ID, physical allocation ID and monotonically increasing execution generation. Workspace binding generation and content version are separate values.
A provider reports an allocation as ready, pending, absent or unknown. Unknown allocation results are inspected by their original request identity. A provider may resume a verified partial allocation under the original intent before admission; it cannot restart an allocation with active uses. New allocations require confirmed absence. Recovery reconciles an active-allocation index before admitting work. Missing providers fail explicitly. Allocation, release and reconciliation retain Runtime-local request ownership through final catalog publication. Reconciliation skips live requests; overlapping explicit provider operations fail with EnvironmentBusy. Failed requests release this ownership, and a new Runtime recovers through the original durable intent. See provider request ownership.
Every acquired use is persisted and blocks deallocation until released. Physical-operation uses survive a Runtime restart; restarting the Runtime is not proof that remote work stopped. Admission uses carry the writing Runtime's epoch and are removed by recovery after that owner is gone. Provider deallocation must confirm physical termination before the catalog returns to idle. Reclamation applies to managed resources after the configured idle interval; borrowed native resources preserve host ownership.
Default selection has an explicit Session, Workspace or Scope reuse policy. The local preset shares one borrowed native Environment per Scope so independent Sessions can use the same live Workspace. Embedded compositions choose their own policy; Harness does not infer users, tenants or billing groups.
EnvironmentResources resolves declared file and execution needs. API-only operations resolve no physical resources. Dormant object-backed files and local directory access do not allocate compute. Execution obtains the target's platform, shell, scratch directory and filtered environment from the Executor, then attaches the selected Workspace. Concurrent admission waits for an attachment already owned by the same Runtime, then revalidates the persisted binding and target. Cancelling a waiter does not cancel the attachment writer; an orphaned or failed preparing view remains unavailable pending explicit recovery. An active view must remain on its recorded target. File-tool authorization accepts the selected object Workspace's validated logical root, including through the isolated policy worker; shell authorization retains the target's physical namespace. Native filesystem access gains no logical alias. Final symlink containment remains with the file host. Backend incompatibility fails before allocation; missing authority never falls back to a controller path.
Environment providers are registered during Runtime composition and sealed before storage startup. Registration is isolated across Runtime instances. Structured records, owner bindings, uses and active indexes share Agent Storage transactions. External allocation, inspection and termination run outside retryable transactions.
The Scope-owned Environment API lists profiles, logical resources, retained uses and unfinished operations. Creation selects a profile without allocating. Session Environment changes compare the previous selection, require an idle Session and drained uses, save/detach its previous Workspace view, and commit the owner binding with Session indexes. New turn admission waits for the Session binding lease before reading execution context. Allocation reclamation and Workspace detachment accept generation/revision preconditions. Environment state changes publish environment.updated through the transactional outbox.
Recovery endpoints inspect existing operation identities and retry confirmed saves. They never submit a replacement command. Unknown execution remains unknown; an unavailable live view remains unavailable. Cancellation requests retain ownership until physical completion and saving. Activity responses exclude file-operation payloads and expose their status and structured failure only.
The decision record explains independent identity and reconciliation. Workspace authority remains defined by Workspace and files.
EnvironmentExecution persists an operation identity, input digest and allocation target before dispatch. Repeated submissions inspect the existing operation. Different inputs for an occupied operation identity fail. A missing executor receipt produces an unknown result, not a repeated command. Cancellation is persisted before transmission and requires executor confirmation.
Command compilers may supply a separate stable intent digest covering the original command, staged input content, target environment, working directory and containment policy. Reconciliation checks that intent while retaining the original compiled digest for Executor receipts. Temporary sandbox filenames cannot cause a second dispatch. Virtual Note inputs are staged by the selected Executor under their execution identity, outside Workspace content; their bytes and containment profiles remain retained until saving and acknowledgement. Early failure may discard inputs only before an execution receipt exists. Bash decodes stdout and stderr independently across binary frame boundaries.
The versioned Executor protocol carries command, PTY, input, cancellation, status and cursor-based output operations. An exit becomes eligible for saving only after native tree and stream drainage are confirmed. Output is copied into Agent Storage artifacts before the caller's checkpoint is published. Saving failure retains the use and physical writer; retries invoke the checkpoint rather than execution. A saved result precedes executor release, and lost release acknowledgements can be retried independently.
EnvironmentProcess presents that protocol as binary process streams with delayed activation, cancellation, PTY resize and an explicit completion promise. Close follows durable saving and consumption of both readable output buffers; physical exit and writable finish alone cannot complete foreground work. Paused consumers retain backpressure through the last byte, while explicit stop resumes drainage. Its output replay uses the same operation identity and never dispatches a completed command again. Only a direct native adapter may expose a controller-local PID; remote PIDs cannot enter native termination or diagnostics paths.
Activation observes running or terminal executor status before output consumption can apply backpressure. An accepted snapshot continues polling even if newer output is already available. See activation observation ordering.
Abort callbacks enter the Runtime that prepared the process before recording cancellation, including signals delivered outside Runtime context. A resource-owning asynchronous scope awaits its operation before disposal; returning an unsettled promise cannot release the selected Environment admission. See asynchronous execution ownership.
Bash declares an execution requirement and accepts an optional Workspace. The resolver admits the selected target before containment and authorization. The Bash backend uses the target shell and environment, records the operation from its call identity, and retains existing process presentation, rollout evidence, native Workspace observation and worktree use. Background acceptance releases the foreground admission and abort subscription; the execution's durable use remains until completion. Direct host invocations without a Session Environment field use the composing host's explicit default. Interactive terminals and user shell commands use the same execution owner, target environment and completion protocol. Terminals retain their execution use while disconnected and expose a native PID only for direct local execution; file context is optional.
Local Runtime registers the borrowed native provider. localRuntime({ environment: false }) omits execution providers and their default selection while retaining Workspace blob factories. Profile discovery lists only registered execution providers. The native executor uses OwnedProcess and the existing Workspace coordinator. Its private receipt spool stores operation status and output, not Sessions or Agent configuration. Durable process claims survive the executor owner and require their recovery reference for release. The coordinator upgrades its host-local ledger under its existing lock: version 2 retains durable claims, and version 3 retains verified process completion before the supervisor removes its native receipt. Older readers reject unsupported versions rather than dropping retention metadata. The Agent Storage schema is unchanged.
Runtime startup indexes and reconciles unfinished executions before admission. Recovery inspects existing receipts, captures missing output, retries checkpoint publication and release acknowledgements, and never resubmits a command. Runtime-owned maintenance repeats recovery and idle reclamation every 15 seconds; shutdown drains this loop before stopping resource owners. Managed allocations become eligible after their configured idle interval; borrowed allocations and active uses remain intact.
A confirmed missing allocation with a retained live Workspace view remains unavailable. The mount cannot silently materialize an older manifest. Preparing mounts may finish their original materialization; saving mounts resume their original checkpoint and detachment.
The global resources configuration domain supplies named Environment and object-storage profiles. The product registers native and configured Docker providers, plus local-object, S3 and OSS factories during composition. Selection copies non-secret settings into durable resource records; subsequent profile edits affect new resources, not existing storage locations or allocations. Credentials and TLS keys are Secret Vault references resolved by their owner. Malformed resource configuration fails closed and is not quarantined into an implicit native default. Project configuration cannot override execution hosts or storage authority.
The built-in native profile remains the default. defaultEnvironment: null disables automatic execution selection. Docker profiles default to Session reuse, while native uses Scope reuse; an explicit profile can choose Session, Workspace or Scope reuse. Defining or selecting a profile never starts compute. External Docker bind mounts and named volumes are read-only inputs; writable files use the coordinated Workspace view.
The Execution Host serves the same Executor over authenticated Unix sockets or HTTPS. Every request carries the allocation target; stale generations fail before dispatch. HTTP controls submission, inspection, cancellation and save acknowledgement. SSE carries cursor-based replay. WebSocket output frames contain a stream discriminator, a big-endian cursor and binary bytes; clients send binary stdin or JSON resize/end controls. Dropped output or terminal-status frames close the connection with status 1013 so consumers can reconnect from their last received cursor. Disconnect does not cancel execution. Transport credentials are private control-plane secrets and never enter command environments.
Execution connections are cached against the Environment's monotonic update timestamp as well as its allocation target. Reconciliation refreshes a changed transport endpoint without changing execution identity or resubmitting commands. See endpoint recovery.
Sandbox preparation and cleanup belong to the selected Executor. The control plane sends policy inputs and receives the target compiler's containment verdict and write footprint. Temporary profile paths remain private to that host; cleanup uses an opaque preparation ID. Native providers delegate to the registered OS sandbox host. An Executor with no sandbox implementation reports unavailable containment.
The Docker provider negotiates Docker Engine API versions over a Unix socket or TLS. A logical Environment lazily creates an identity-labelled container and private bridge network. The host incarnation is fenced by container identity and start time; externally restarting the container requires reconciliation. Managed containers use a read-only root, bounded temporary filesystems and resources, and a supervisor that launches user commands as UID 1000 without its credentials or effective capabilities. Bind sources are paths on the Docker daemon host. User-supplied named volumes outlive allocation deletion. Remote execution listeners require TLS. The transport decision records the protocol and isolation choices.
The Docker image compiles Linux sandbox profiles on the execution host and uses the same bubblewrap policy as native Linux execution. Its outer seccomp policy permits unprivileged namespace setup; the remaining upstream syscall restrictions remain enabled. The outer procfs has no child overmounts, allowing each command sandbox to mount a private PID namespace. Commands remain UID 1000 without capabilities or supervisor credentials. Kernel or security-module rejection fails the command; there is no automatic unconfined retry.
Native execution adapters can provide a bounded waitForChange hint after status or durable output changes. The process facade still reconciles canonical operation and allocation authority on every wake and at least every 250 ms while idle; adapters without notifications retain polling. Unchanged validated observations avoid entering the storage writer queue, and an unchanged output cursor avoids an empty output read. Cancellation, terminal stream drainage, checkpoint publication and release remain owned by the existing execution protocol. See bounded observation work.
Tool discovery and execution use the Session's selected Workspace ID even when there is no local directory. Listing capabilities neither materializes files nor allocates compute; permission and user-tool filters remain independent.
Plugin file and shell Host Services resolve the invocation's pinned resource selection. Dormant files require no allocation; shell execution uses the same Environment process facade as first-party tools. Native file-host admission inherits its calling task's reservation while retaining a separate durable physical writer. This permits a shell followed by a file write in one invocation without bypassing foreign-writer exclusion or losing a writer on interrupted saving.
WorkspaceMounts persists one active writable view per Workspace with its own mount generation and allocation target. Attachment transfers verified object chunks and materializes their manifest through the Executor's file host. Directory attachment requires an explicitly resolved provider path. A failed or uncertain attachment retains its Environment use for reconciliation. File inspection, bounded reads, versioned writes, checkpoint transfer and acknowledgement use the same file host directly or over transport.
Execution records pin their explicitly selected Workspace mounts before dispatch and retain resource use through process exit, output drainage, checkpoint publication and release acknowledgement. Cancellation confirmed before activation needs no checkpoint. Managed file mutations retain their concrete writer until acknowledgement and reject stale preconditions before effects. Missing receipts remain unknown, and side effects are never replayed solely to retry saving.
Materialized object-backed views publish content manifests. Directory and volume views retain files in their owning filesystem and publish a completion receipt with no object manifest. Those receipts still require physical writer completion and acknowledgement; ordinary native commands do not scan and upload the entire directory.
Reconciliation of a releasing Environment resumes resource checkpoints and provider deallocation using its original allocation identity, even when compute is already absent. Repeated saving or provider failure preserves that release intent through startup recovery and maintenance; allocation state clears only after complete retirement. See release recovery.
Environment deallocation first closes admission through its durable releasing state. Workspace resource owners publish a final checkpoint, detach the live views and clear their fenced bindings before the provider destroys compute. Docker uses an allocation-owned staging volume for materialized views; that volume is deleted after these checkpoints, while explicitly supplied Workspace volumes remain intact. Reallocation restores files into a new view and increments allocation and mount generations independently. See checkpoint ownership.
Explicit Workspace detachment fences new admission through the mount’s saving state, retains a durable use across failed checkpoints, and can resume the same save/detach operation. Rebinding a directory first detaches its idle live view. Active Environment users prevent detachment; directory view registration itself only pins identity and does not reserve a writer. Workspace-scoped state can be selected by logical ID and binding generation without supplying a local path.
File-history evidence uses immutable before/after manifests from the explicitly captured mounts. Object snapshot identities include Workspace identity and binding generation. Overlapping native write intervals and refreshed save attempts remain incomplete evidence instead of authorizing undo of another task. Dormant edits publish their head and evidence in one transaction; restore checks binding generations and exact byte versions.
Language servers use the same durable execution facade for native and remote allocations. Cooperative services report contention from their owning Executor; idle clients retire after active queries finish and release their writers only after checkpoint publication. Queries read document bytes from the selected file view. Configured LSP commands run inside the selected Environment and must exist in its image or Workspace; native directory discovery retains its local installers. Dormant file browsing does not start a language server or allocate compute.
Configured formatters execute in the selected Environment. Command file preconditions carry the committed byte version and canonical target path; the Executor validates them after acquiring the physical writer and before activating the process. Rejected preconditions never dispatch a command and remain immutable on retry. File-version reads use the selected file view. Dormant object edits skip automatic formatting, while active views retain execution through output and file saving. A failed launch with verified tree and stream drainage can be saved and released; only unverified completion retains an unknown outcome.
Environment catalog events and snapshots use a strictly increasing per-resource update timestamp. Session Environment changes validate the route Scope and compare the observed previous selection before mutation.
Browser and native Computer operations retain their host-specific implementations and require a Session selecting the native Environment. Environment transitions close the Session Browser before committing. Managed Git worktree creation and entry require a native directory context and native Session Environment; remote Git commands use Bash in the selected view. Controller preparation callbacks cannot run as part of a remote Workspace command.
Checkpoint attempts persist their expected binding, mount target, content revision and immutable receipt identity before capture or mutation. A stale attempt cannot publish over a newer head. Conflict leaves execution unsaved; recovery records a new attempt and captures the current shared view without re-executing the command. Earlier attempts remain available for reconciliation. A published attempt retains its result across lost acknowledgements. The 20260929-workspace-checkpoint-attempts migration recaptures unfinished legacy receipts because they lack a frozen publication base; it does not clear retained native claims.
Local Runtime accepts an optional environmentProfile on session.create, mutually exclusive with environmentID. It resolves a configured profile into the existing Harness provider descriptor, and Harness applies the existing Session/Workspace/Scope reuse policy during initial creation. For a copy with Workspace reuse, file identity is resolved before the initial Environment binding. Selection and preview do not allocate compute. Invalid profiles and incompatible file locations fail explicitly. Profile summaries retain explicitly configured invalid defaults for repair; the implicit native default is absent when the composition has no native execution provider.
Workbench owns defaultSessionEnvironmentProfile and defaultSessionWorkspace. App resolves these defaults only for new Web/Desktop tasks and passes explicit creation intent. An omitted execution preference inherits; null selects no command execution; a string references a global resource profile. These preferences never redefine API, Channels or Cortex creation. Project-default updates use a scoped, revision-checked endpoint that writes only those two keys to the project general domain. Projects without a configuration folder expose inherited defaults read-only. Existing Sessions remain unchanged.
Ordinary Web/Desktop project entry selects a computer by service connection and couples its native execution profile to that service's filesystem. Only managed Desktop's matching running service can claim local-computer identity or use a native directory picker. Product previews do not allocate Environments. Existing non-native profiles and stored-file configurations retain their actual binding and a developer-management repair entry; the public API's independent Workspace/Environment capability is unchanged. See project entry.