# Workspace upgrade policy

Decide whether existing runs move to a new deployment before their next turn.

Each deployment declares how it affects existing durable runs.

## Automatic upgrades

```yaml
runtimeConfig:
  workspaceUpgradePolicy: automatic
```

Before the next turn on an eligible existing run, Salambo:

1. Claims the run upgrade lease.
2. Checkpoints the current workspace.
3. Creates a sandbox from the active deployment.
4. Restores the existing workspace.
5. Validates the target runtime.
6. Atomically switches the run to the new sandbox and deployment.
7. Executes the requested turn.
8. Saves a post-turn checkpoint before reporting completion.

The old sandbox remains authoritative until the switch succeeds.

## New-run-only upgrades

```yaml
runtimeConfig:
  workspaceUpgradePolicy: new-run-only
```

Existing runs remain pinned. Only new runs use the deployment.

## Workspace preservation rule

The new deployment's seed is never merged into an existing run. Existing workspace files are restored byte-for-byte from the run checkpoint.

## Failure behavior

| Failure                     | Result                                                          |
| --------------------------- | --------------------------------------------------------------- |
| Checkpoint fails            | Old sandbox remains authoritative                               |
| New sandbox creation fails  | Old sandbox remains authoritative                               |
| Restore or validation fails | Replacement is discarded and retry remains possible             |
| Atomic switch succeeds      | New sandbox becomes authoritative and old compute is cleaned up |
| Post-turn checkpoint fails  | Turn fails instead of claiming durable completion               |

Use `new-run-only` for changes that should not affect an existing session. Use `automatic` when compatible runs should adopt the latest deployment while preserving their workspace.