# Workspace Execution

**Status:** Approved target-state baseline  
**First realization:** I0 substrate / I1 live coding  
**Provider:** native Kubernetes WorkspaceProvider.

## Target State

`Workspace` is the durable AWP abstraction for an isolated execution environment. Kubernetes Pod/PVC/ServiceAccount/NetworkPolicy mechanics implement it through `WorkspaceProvider`.

```text
immutable source revision
  -> resolved ExecutionProfile
  -> isolated Workspace
  -> AgentRun Attempt
  -> durable checkpoints/WIP
  -> ChangeSet collection
  -> cleanup disposable compute
```

## Invariants From Day 1

- normal AgentRuns do not execute on the user's workstation;
- workspace starts from a known immutable repository/base revision;
- `ExecutionProfile` is immutable for an Attempt and records toolchain/services/security/capabilities;
- runnable execution images are OCI-registry artifacts pinned by immutable digest; node-local preload/import state is never an execution prerequisite;
- kubelet/containerd may cache or K3s/Spegel may mirror an image transparently, but AWP records the registry digest as desired state and never models per-node image copies as product state;
- private registry credentials are system-scoped pull authority used by kubelet and are not mounted into AgentRun containers; missing pull authority is configuration drift and blocks dispatch before workspace creation;
- compute is disposable; recoverable WIP is not;
- cleanup cannot destroy the only copy of uncollected work/evidence;
- provider/account/model fallback creates a new Attempt; workspace reuse/resume is explicit;
- no reusable Git publication credentials inside workspace;
- resource/network/privilege controls are explicit profile properties;
- source/cache/service attachments have declared ownership and cleanup.

## ExecutionProfile Resolution

Prefer project-native environment declarations in this order where applicable:

```text
.devcontainer
Docker/Compose
mise/Devbox
language/tool manifests
AWP project profile only for missing orchestration metadata
```

Resolved profile includes:

- image/toolchain identity;
- CPU/memory/storage requests/limits;
- runtime class/sandbox;
- workspace persistence mode;
- service attachments;
- network egress policy;
- credential projections;
- timeout/cancellation policy;
- capability/placement requirements;
- provenance of each inferred/overridden value.

## WIP and Checkpoints

Checkpoint semantics must survive:

- process crash;
- pod deletion/replacement;
- control-plane restart;
- user cancel/retry;
- recoverable node interruption.

Checkpoint may be Git object/bundle, PVC snapshot/materialization, object-store archive or provider-specific mechanism, but AWP records immutable checkpoint identity/digest and originating Attempt.

## Workspace Lifecycle

```text
requested -> preparing -> ready -> in-use
  -> checkpointing/collecting
  -> released -> cleaning -> cleaned

failure branches:
preparation-failed
execution-interrupted
cleanup-failed (Incident if resources leak)
```

Cleanup is idempotent and separately observable from logical run completion.

## Placement

Workspace requirements become scheduling constraints over `MachineCapability`: architecture, CPU/RAM/storage, GPU, runtime class, trust tier, labels/capabilities and locality. AWP records `PlacementDecision` when placement becomes product-visible.

## Increment Realization

| Increment | Workspace realization |
|---|---|
| I0 | native K8s provider, profiles, PVC/checkpoint strategy, isolation/recovery tests. |
| I1 | live coding/reviewer Attempts and WIP preservation. |
| I4 | rich files/checkpoints/tool/log observability. |
| I7 | cluster scheduling/capacity/placement UX. |
| I9 | tenant quotas/isolation hardening. |

## Current Implementation State

No workstation worktree lifecycle is carried forward as target architecture. Git worktree concepts may exist inside implementation/provider mechanics if useful, but Workspace remains the product abstraction.

## Deferred Realization

Kubernetes Agent Sandbox, Kata, Kueue and advanced sandbox/scheduler components remain trigger-only FOSS choices.

## Temporary Dogfood Behavior

Initial I1 may use a simple per-run PVC/checkpoint method and one K3s cluster. It must still pass pod/process failure and recoverability tests before real dogfood work is trusted.

## Decisions / ADRs

See ADR 0006. Any change that makes WIP ephemeral or returns normal execution to workstation requires superseding Decision.