# Spec 002: isolated execution

Status: draft revision 2 for review
Date: 2026-08-08
Depends on: [Spec 000](spec-000-system-overview.md) and [Spec 001](spec-001-core-and-live-work.md)

## Outcome

A Godloop-created coding agent can damage only its disposable environment. Its
changes return as a reviewable result; they never write directly into a
developer's current checkout or production.

This spec owns execution isolation and change handoff. It does not own project
events or FirstMate behavior.

## One execution lease

```text
Execution
   │
   ├── base commit + dedicated branch/worktree
   ├── independent Crabbox workspace
   ├── Herdr endpoint
   └── Result + cleanup receipt
```

These resources share one execution ID and one lifecycle. Godloop stores their
public identifiers and receipts; the Space connector owns local paths and
provider credentials.

## Two explicit modes

`sandboxed` is the default for Godloop-created coding work after its feasibility
gate passes. The agent runs in an independent Crabbox workspace with bounded
resources, credentials, and network.

`trusted_local` represents a manually started Herdr agent on the Space owner's
machine. It is visible but never mislabeled as sandboxed. Team control is off
unless that owner opts in.

Failure to provision `sandboxed` work fails closed. There is no automatic local
fallback.

## Worktree and sandbox are different

The worktree owns a branch and provides collision-free change review. It is not
a security boundary.

Crabbox owns compute isolation. It receives an independent checkout seeded from
the execution's immutable base; the host checkout, home directory, Docker
socket, SSH agent, ambient environment, and unrelated repositories are not
mounted into it.

The coding agent works in the sandbox copy. On completion, a bounded patch and
manifest are verified against the base and materialized into the execution's
dedicated review worktree. This keeps untrusted compute away from the host while
retaining ordinary Git review and integration.

Dirty developer changes are excluded unless the user explicitly creates a
reviewable snapshot. The connector never guesses whether uncommitted work was
intended.

## Provisioning flow

1. Persist an authorized `Execution` in `provisioning` state.
2. Resolve and record an immutable base commit.
3. Create a uniquely named branch and managed review worktree outside the
   developer's selected checkout.
4. Start a fresh Crabbox workspace from the same base and the trusted
   repository policy.
5. Open a background Herdr endpoint attached to the sandboxed agent without
   changing user focus.
6. Prompt only after all returned identities are bound to the execution.
7. Reconcile Herdr lifecycle and collect a typed result.
8. Verify the patch manifest, materialize it in the review worktree, and run
   declared checks.
9. Retain the result for review; clean runtime resources only after terminal
   state is confirmed.

No label, terminal title, current focus, or agent-provided path is trusted as an
identity.

## Feasibility gate

Before application code depends on this flow, one isolated spike must prove:

- Crabbox can seed the exact committed source without a host mount;
- a supported agent can run inside it while Herdr reports usable lifecycle;
- prompt, blocked, completion, reconnect, and cancellation can be observed;
- patch and test evidence can return without granting the sandbox host access;
- two concurrent executions cannot read or write each other's files;
- cleanup is confirmable and idempotent.

Run the spike in a named test session and fixture repository. If Herdr cannot
reliably supervise the Crabbox terminal, stop and revise this spec. Do not add a
second runner or silently weaken isolation.

The repository's current `.crabbox.yaml` is a validation profile, not evidence
that interactive agents already satisfy this gate.

## Policy

Provider, image, resources, sync rules, credentials, and network are selected
from a trusted server/Space policy. Repository code may request a narrower
profile but cannot widen it.

Default sandbox policy:

- no host mounts or privileged container features;
- no ambient secrets;
- no network unless the declared task needs an allowlisted destination;
- credentials scoped to one task and removed at cleanup;
- time, CPU, memory, disk, and output bounds;
- no deploy, publish, push, or production access without a separate approved
  command.

## Result and apply

The typed Result contains:

```text
status
summary
base commit
changed-file manifest and patch digest
tests and bounded logs
artifacts
Herdr and Crabbox receipts
cleanup state
```

Terminal text alone is not a result. A successful agent exit does not imply
valid changes, passing tests, cleanup, or apply.

Review compares the manifest to the materialized worktree. Apply is a new,
authorized command that integrates from that worktree or publishes its branch.
It never writes into whichever checkout happens to be open.

Every writing child receives its own execution lease. Read-only children may
share an immutable source snapshot, but never a writable filesystem.

## Recovery rules

- Provisioning interrupted: reconcile by execution ID and returned provider
  identities before creating anything else.
- Agent disappears: keep the worktree and artifacts, mark execution failed,
  and confirm sandbox cleanup.
- Result invalid: quarantine the bounded artifacts and do not materialize or
  apply the patch.
- Cleanup unconfirmed: keep the lease non-terminal and visible for repair.
- Base advanced before apply: require review against the new base; never force.
- Space revoked: stop new dispatch and follow the recorded cancellation policy
  for active work.

## Acceptance

1. Start two writing agents from one base.
2. Each receives a distinct branch, review worktree, Crabbox workspace, and
   Herdr endpoint without stealing focus.
3. Each may destroy its sandbox copy but cannot observe the host checkout,
   ambient credentials, the other execution, or production.
4. Restart Godloop and the connector while both work; identities and lifecycle
   reconcile without duplicates.
5. Each returns a verified patch and evidence to only its own review worktree.
6. Reject one result and apply the other through an explicit command.
7. Confirm all runtime cleanup while retaining durable results and review
   history.

## Not in this spec

- generic remote desktop or arbitrary SSH access;
- Kubernetes, a sandbox scheduler, reusable warm pools, or multiple providers;
- automatic merging, pushing, deployment, or secret injection;
- claiming worktrees or the current local-container profile are security
  sandboxes.