Epic: Grove Oven — maintain ready-to-claim hot workspaces

[nicksong-z]

Product goal

Grove Oven exists to deliver near-zero wait time between requesting a task workspace and handing a ready environment to a coding agent.

Containerization and sandboxing are enabling mechanisms and side benefits. They are not the primary goal. A prebuilt image that starts downloading only after gw grab is still a cold workspace.

Grove Oven keeps likely agent workspaces ready to claim.

Target golden path:

gw grab https://github.com/acme/api/pull/123 --agent codex

✓ Resolved PR #123 — Add partial refunds
✓ Matched payments blueprint
✓ Claimed hot workspace slot
✓ Created task branches across 3 repos
✓ Injected agent context
✓ Launched Codex

Ready in 3.4s

Core mental model

The Oven lifecycle is:

Bake → Preheat → Claim → Replenish

1. Bake

Ahead of user demand:

• resolve a Preset 2.0 blueprint;
• resolve base revisions and toolchain inputs;
• build the OCI/Dev Container environment from Grove 1.2: Containerized agent workspaces and handoff #64;
• assemble the blueprint's repository topology;
• install dependencies and generate reusable assets;
• run readiness checks; and
• produce immutable, fingerprinted artifacts/snapshots.

2. Preheat

On the developer's machine, before a workspace is requested:

• fetch relevant Git refs;
• pull required container images;
• restore dependency/cache artifacts;
• instantiate one or more ready workspace slots; and
• verify that each slot meets the blueprint's readiness contract.

3. Claim

On the user-facing path:

• resolve the task and select the blueprint;
• atomically claim a compatible ready slot;
• create/switch the task branches from the prepared base revisions;
• attach source provenance and generate agent handoff context;
• start or attach to the prepared container; and
• launch the requested agent.

No cloning, image pulling, dependency installation, large copying, or full build should occur on the HOT path.

4. Replenish

Immediately after a slot is claimed, the local Oven prepares its replacement in the background while respecting CPU, network, concurrency, and disk budgets.

Hotness contract

Oven should expose explicit states rather than calling every cache hit “hot”:

State	Available locally	Target experience
HOT	Compatible ready slot, image, refs, dependencies, readiness proof	Agent launched in <5s
WARM	Image and reusable artifacts local; slot must be instantiated	Agent launched in <20s
COLD	Required image/artifacts/build missing	Correct fallback; no latency promise

Initial targets should be validated on a documented reference machine and representative three-repo blueprint. Track p50 and p95 rather than reporting only a best-case demo.

gw oven status payments

Blueprint: payments
State:     HOT
Slots:     1 ready, 1 baking
Image:     local @ sha256:abc...
Git refs:  current
Deps:      prepared
Expected claim time: 3–5s

Architecture

Optional team/CI Bakery

The Bakery performs expensive shared preparation once:

• builds signed/pinned OCI images;
• prepares reusable dependency or generated-asset layers;
• publishes immutable manifests and blobs; and
• never embeds user secrets.

Git remains the source for reviewed blueprint definitions. OCI is the natural first transport for container images and reusable layers. S3-compatible artifact transport may follow when demanded.

Core local Oven

A local reconciler moves network, CPU, and setup work before the request:

Team/CI Bakery
      ↓ immutable images/artifacts
Core local Oven
  ├── prefetch images
  ├── fetch Git refs
  ├── prepare workspace slots
  ├── validate readiness
  └── maintain desired capacity
      ↓
gw grab/create
  └── claim slot and hand off to agent

Near-zero latency requires resource consumption before demand. The user must be able to control:

• which blueprints stay hot;
• desired ready-slot count;
• disk limit and retention;
• background CPU/network concurrency;
• metered-network and battery behavior; and
• pause/resume/disable state.

A daemon/reconciler is likely required for the fully magical experience. Manual preheat must remain available for users who do not want a background process.

Hot workspace slot

A HOT slot is a local, workspace-scoped prepared environment for exactly one blueprint fingerprint. It may contain:

• host-side detached worktrees at resolved base revisions;
• installed or immediately reusable dependencies;
• generated public assets;
• a pulled/prepared container image;
• a created or running workspace container;
• agent CLI/tooling;
• readiness results and provenance; and
• no personal secrets or task-specific branch state.

When claimed, the slot becomes an ordinary durable Grove workspace: source changes remain in host-side worktrees, while the agent runs inside the container defined by #64.

Stable slot paths, worktree registration/repair, workspace naming/aliases, and whether containers are pre-created or already running are explicit design questions. The chosen design must meet the HOT SLO without hiding fragile Git metadata moves.

Blueprint configuration sketch

Illustrative only:

[oven]
enabled = true
min_ready = 1
max_ready = 2
max_disk = "20GB"
hot_target = "5s"
refresh = "on-base-change"

[oven.resources]
max_concurrent_bakes = 1
allow_metered_network = false
allow_on_battery = false

The Oven fingerprint should include all inputs that can affect compatibility:

• resolved blueprint content and schema version;
• OS/architecture and container runtime requirements;
• OCI image digest and relevant toolchain versions;
• repository identities and resolved base revisions;
• declared lockfiles/setup inputs; and
• preparation commands and readiness contract.

A changed fingerprint never mutates a claimed workspace. It marks unclaimed slots stale and causes controlled replacement.

Core ownership

Oven is part of Grove core because claiming/hydrating must participate in the same plan, transaction, rollback, state, doctor, and cleanup paths as workspace creation.

Grove core owns:

• Oven fingerprints and compatibility;
• local slot state and reconciliation;
• bake/preheat/claim/replenish semantics;
• the default local content-addressed store;
• artifact integrity and safe extraction;
• readiness checks and hotness classification;
• fallback, invalidation, retention, quotas, and garbage collection;
• gw oven bake/preheat/status/clean/pause/resume;
• transactional conversion from slot to workspace;
• gw apply --hot; and
• doctor plus agent-native structured output.

Keep these packages internal initially. Do not publish a stable Go API before the lifecycle has proven itself.

Extensions/adapters own:

• S3 authentication and transport;
• OCI registry authentication beyond the selected runtime's normal mechanism;
• cloud-specific cache/storage implementations;
• Ona/Coder/remote-runner integrations; and
• full VM or microVM snapshot systems.

Remote adapters transport immutable manifests/blobs only. Core verifies all digests and controls extraction and workspace paths.

CLI sketch

# Build preparation artifacts explicitly
gw oven bake -f grove.workspace.toml

# Instantiate/refresh local ready capacity
gw oven preheat payments

# Run or install the background reconciler
gw oven serve

# Explain state, misses, compatibility, resource use and timing
gw oven status payments --format json

# Control local resource consumption
gw oven pause
gw oven resume
gw oven clean --max-disk 20GB

Normal gw create, gw apply, and gw grab automatically claim a compatible HOT slot when policy permits, and clearly report WARM/COLD fallback.

Security and trust

• Bakes and ready slots never contain user secrets, model tokens, Git credentials, personal .env files, or task-specific credentials.
• Shared baking uses a dedicated service identity with minimal source access.
• Every image/artifact is pinned and verified by digest before use.
• Archive extraction rejects path traversal, unsafe links, devices, and writes outside controlled roots.
• Setup/preparation commands from changed remote blueprints require renewed approval.
• Unclaimed slots run no unreviewed task code.
• Claimed agent containers inherit the least-privilege runtime profile defined by Grove 1.2: Containerized agent workspaces and handoff #64.
• Corrupt, untrusted, incompatible, or stale slots are quarantined and never silently claimed.

Delivery slices

1. Establish latency baseline on Grove 1.2

• Use Grove 1.2: Containerized agent workspaces and handoff #64 to measure cold containerized handoff for a representative three-repo workspace.
• Define the exact “request → agent running” timer and reference environment.
• Record image pull, Git preparation, dependency setup, container startup, and handoff components separately.

2. Manual local preheat

• Define the Oven fingerprint and readiness contract.
• Add explicit bake/preheat/status commands.
• Pull images, fetch refs, and prepare one local slot ahead of demand.
• Claim the slot transactionally and fall back cleanly on miss.
• Prove the HOT path can meet the target without a daemon.

3. Core warm-pool reconciler

• Maintain min_ready per enabled blueprint.
• Replenish after claims and replace stale slots safely.
• Enforce disk, CPU, network, concurrency, and retention policy.
• Recover after process/system restart without leaking containers/worktrees.
• Expose health, timing, and miss reasons through Epic: Replace MCP with an agent-native CLI #63.

4. Team Bakery and remote artifacts

• Publish immutable OCI images/artifacts from CI.
• Prefetch and verify remote content before demand.
• Add optional signatures/attestations and cache-poisoning policy.
• Evaluate S3 transport only after OCI/local usage demonstrates need.

Acceptance criteria

• A documented representative HOT three-repo workspace launches its configured agent in under 5 seconds at p95 on the reference environment.
• The HOT path performs no image pull, repo clone, dependency install, or full build.
• Claiming creates the correct task branches and preserves host-side Git/worktree integrity.
• Claimed changes remain durable after the agent container exits or is destroyed.
• Replenishment restores desired ready capacity without blocking the user.
• Changed blueprint/base/image/setup inputs invalidate only affected unclaimed slots.
• WARM and COLD paths remain correct and explain why the HOT target was missed.
• Corrupt or interrupted bake/preheat state never blocks ordinary cold workspace creation.
• Disk/resource policies are enforced and garbage collection never touches claimed workspaces.
• No secrets are persisted in shared artifacts or unclaimed slots.
• Unit, integration, and e2e tests cover claim races, interruption, stale slots, quotas, restart recovery, and fallback.

Non-goals

• Making an arbitrary never-seen blueprint instantly available without prior resource use.
• Hiding cold starts or reporting a cache hit as HOT when the SLO cannot be met.
• Replacing OCI, Dev Containers, package managers, or container runtimes.
• Building a hosted workspace service, VM platform, or general CI system.
• Predicting assigned tasks or integrating issue trackers before deterministic preheat works.
• Deleting or mutating claimed workspaces when the Oven refreshes.

Dependencies

• Epic: Make workspace operations transactional and recoverable #59 — transactional workspace/slot claim, rollback, locking, and recovery.
• Epic: Replace MCP with an agent-native CLI #63 — agent-native plans, context, status, errors, and timing output.
• Grove 1.2: Containerized agent workspaces and handoff #64 — containerized agent runtime and host-worktree handoff foundation.
• Epic: Blueprints — presets as code (Preset 2.0) #61 — Preset 2.0 blueprint, setup, preparation, and readiness contract.
• Epic: Turn a task or PR URL into a ready workspace with gw grab #60 — task/PR intake that selects a blueprint and claims a hot slot.