diff --git a/AGENTS.md b/AGENTS.md
index 8b95342..241075b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,57 +1,6 @@
-# Agent Context for Drover Code
+# Agent Context
 
-Welcome, AI Agent. This file is intended to help AI coding assistants understand the structure, context, and conventions of the `drover-code` repository.
-
-## Ecosystem Role
-
-> **Part of the Drover Ecosystem**: `drover-code` serves as the **Core Agent Engine**. It is the fast, static Go binary that actually runs the agentic loop, calls the Anthropic API (via `drover-gateway`), and executes tools. It is orchestrated by `drover` and runs headlessly inside `drover-cloud` unikernels.
-
-## What this repo is
-
-## Layout
-
-| Path | Role |
-|------|------|
-| `cmd/drover-code` | CLI entry: TUI, headless, `webhook`, flags |
-| `cmd/ukc-agent` | HTTP agent for Unikraft Cloud instances (workspace sync & exec) |
-| `internal/agent` | Agent loop, events |
-| `internal/api` | HTTP client, SSE stream |
-| `internal/bridge` | IDE bridge (JSON-RPC framing over stdio) |
-| `internal/config` | Settings merge, `CLAUDE.md` / markdown injection |
-| `internal/integrations/sqlforge` | Detect `sqlforge.yml`; inject SQLForge CLI guidance |
-| `internal/convo` | Conversation state, compaction heuristics |
-| `internal/coordinator` | Multi-worker coordinator mode |
-| `internal/github` | Webhook server, parser, runner |
-| `internal/tools` | Tool registry and implementations |
-| `internal/tui` | Bubble Tea model and views |
-| `internal/dream` | Session memory (JSON / SQLite) |
-| `design/` | Design specs and roadmap (numbered `01-…`, test plan `13`, UX `14`) |
-| `docs/` | User-facing docs (Tutorials, How-Tos, Reference, Explanation) |
-
-## Build and test
-
-```bash
-CGO_ENABLED=0 go build -o drover-code ./cmd/drover-code
-CGO_ENABLED=0 go build -o ukc-agent ./cmd/ukc-agent
-CGO_ENABLED=0 go test ./...
-```
-
-CI uses Go 1.22 with `CGO_ENABLED=0`. Local `go.mod` may list a newer `go` directive; keep changes compatible with CI unless you bump the workflow.
-
-Fuzz targets are listed in `.github/workflows/ci.yml` (`fuzz` job).
-
-## Conventions
-
-- Prefer focused changes: match existing style, imports, and error wrapping in touched packages.
-- Property / fuzz tests: see `design/12-property-fuzz-testing.md` and doc `13-test-coverage-plan.md`.
-- Do not assume Node: this is Go-only for the main binary.
-
-## Product behavior pointers
-
-- End-user overview, env vars, and modes: `README.md`.
-- `internal/config` walks upward from `workDir` and merges `CLAUDE.md` files into the system prompt. If this repository is the working directory, **this** `CLAUDE.md` is included like any other project instructions file.
-- When `sqlforge.yml` is found at a project root, SQLForge CLI guidance is appended automatically. How-to: `docs/how-to/sqlforge-from-drover-code.md`.
-
-## Optional evals
-
-Live Anthropic eval tests are opt-in (`RUN_AGENT_EVALS=1` and API key); see `evals/` and `README.md`.
+> **Note to AI Agents:** 
+> The comprehensive context, repository structure, and operational guidelines for `drover-code` have been migrated to adhere to the organization's strict Diátaxis documentation structure. 
+> 
+> Please read the authoritative agent context here: **[`docs/reference/agent-context.md`](docs/reference/agent-context.md)**
diff --git a/README.md b/README.md
index 213cbab..b68326c 100644
--- a/README.md
+++ b/README.md
@@ -17,8 +17,9 @@ Docs under `docs/` follow [Diátaxis](https://diataxis.fr/) and require YAML fro
 - [Integration Checklist](docs/how-to/integration-checklist.md)
 
 **Reference (Information-oriented):**
-- [Agent Personas & Context](AGENTS.md)
+- [Agent Personas & Context](docs/reference/agent-context.md)
 - [Available Tools](docs/reference/available-tools.md)
+- [Environment Variables](docs/reference/environment-variables.md)
 - [Implementation Requirements](docs/reference/implementation-reqs.md)
 - [Requirements Index](docs/reference/requirements-index.md)
 - [Requirements Summary](docs/reference/requirements-summary.txt)
@@ -28,26 +29,26 @@ Docs under `docs/` follow [Diátaxis](https://diataxis.fr/) and require YAML fro
 - [Architecture Overview](docs/explanation/architecture-overview.md)
 - [Unikraft Cloud Architecture](docs/explanation/unikraft-cloud.md)
 
-**Design Specifications (`design/`):**
-- [01 Foundation](design/01-foundation.md)
-- [02 Agent Loop](design/02-agent-loop.md)
-- [03 Tools Overview](design/03-tools-overview.md)
-- [04 FS Tools](design/04-fs-tools.md)
-- [05 Shell Search Tools](design/05-shell-search-tools.md)
-- [06 Git Web Tools](design/06-git-web-tools.md)
-- [07 TUI](design/07-tui.md)
-- [08 Config & Permissions](design/08-config-permissions-undercover.md)
-- [09 Advanced Systems](design/09-advanced-systems.md)
-- [10 Integrations](design/10-integrations.md)
-- [11 Headless Orchestration](design/11-headless-orchestration.md)
-- [12 Property Fuzz Testing](design/12-property-fuzz-testing.md)
-- [13 Test Coverage Plan](design/13-test-coverage-plan.md)
-- [14 UX Memory Improvements](design/14-ux-memory-improvements.md)
-- [15 UKC Tools](design/15-ukc-tools.md)
-- [16 UKC Workspace Sync](design/16-ukc-workspace-sync.md)
-- [17 Custom Commands](design/17-custom-commands.md)
-- [Claude Go Design Spec](design/claude-go-design-spec.md)
-- [Claude Go Test Spec](design/claude-go-test-spec.md)
+**Architecture Decision Records (`docs/adr/`):**
+- [01 Foundation](docs/adr/01-foundation.md)
+- [02 Agent Loop](docs/adr/02-agent-loop.md)
+- [03 Tools Overview](docs/adr/03-tools-overview.md)
+- [04 FS Tools](docs/adr/04-fs-tools.md)
+- [05 Shell Search Tools](docs/adr/05-shell-search-tools.md)
+- [06 Git Web Tools](docs/adr/06-git-web-tools.md)
+- [07 TUI](docs/adr/07-tui.md)
+- [08 Config & Permissions](docs/adr/08-config-permissions-undercover.md)
+- [09 Advanced Systems](docs/adr/09-advanced-systems.md)
+- [10 Integrations](docs/adr/10-integrations.md)
+- [11 Headless Orchestration](docs/adr/11-headless-orchestration.md)
+- [12 Property Fuzz Testing](docs/adr/12-property-fuzz-testing.md)
+- [13 Test Coverage Plan](docs/adr/13-test-coverage-plan.md)
+- [14 UX Memory Improvements](docs/adr/14-ux-memory-improvements.md)
+- [15 UKC Tools](docs/adr/15-ukc-tools.md)
+- [16 UKC Workspace Sync](docs/adr/16-ukc-workspace-sync.md)
+- [17 Custom Commands](docs/adr/17-custom-commands.md)
+- [Claude Go Design Spec](docs/adr/claude-go-design-spec.md)
+- [Claude Go Test Spec](docs/adr/claude-go-test-spec.md)
 
 ## Requirements
 
@@ -115,7 +116,7 @@ export CLAUDE_CODE_COORDINATOR_MODE=1
 export ANTHROPIC_MODEL=claude-haiku-4-5-20251001
 ```
 
-or `"model"` in `~/.claude/settings.json` or `.claude/settings.json`.
+or `"model"` in `~/.drover/settings.json` or `.drover/settings.json`.
 
 ## Other LLM providers (Moonshot, GLM, …)
 
@@ -125,11 +126,11 @@ drover-code targets the **Anthropic Messages API** wire format. Gateways that im
 
 ## Configuration
 
-Settings merge in order:
+Settings merge in order (legacy `~/.claude` / `.claude` paths at each tier are still read when present; drover wins at the same tier):
 
-1. `~/.claude/settings.json`
-2. `<workdir>/.claude/settings.json`
-3. `<workdir>/.claude/settings.local.json`
+1. `~/.drover/settings.json`
+2. `<workdir>/.drover/settings.json`
+3. `<workdir>/.drover/settings.local.json`
 
 `CLAUDE.md` files under the working tree are concatenated and injected into the system prompt.
 
diff --git a/cmd/drover-code/envutil.go b/cmd/drover-code/envutil.go
index d06c175..5b79242 100644
--- a/cmd/drover-code/envutil.go
+++ b/cmd/drover-code/envutil.go
@@ -32,20 +32,28 @@ func envIntPositive(key string) int {
 	return n
 }
 
-// anthropicAPIKey returns the first non-empty of ANTHROPIC_API_KEY or
-// ANTHROPIC_AUTH_TOKEN (Moonshot/Kimi and some other shims use the latter).
+// anthropicAPIKey returns the first non-empty API key from the environment.
+// It checks Anthropic, Gemini, and OpenAI keys to support API gateways.
 func anthropicAPIKey() string {
-	if v := strings.TrimSpace(os.Getenv("ANTHROPIC_API_KEY")); v != "" {
-		return v
+	keys := []string{
+		"ANTHROPIC_API_KEY",
+		"ANTHROPIC_AUTH_TOKEN",
+		"GEMINI_API_KEY",
+		"OPENAI_API_KEY",
 	}
-	return strings.TrimSpace(os.Getenv("ANTHROPIC_AUTH_TOKEN"))
+	for _, k := range keys {
+		if v := strings.TrimSpace(os.Getenv(k)); v != "" {
+			return v
+		}
+	}
+	return ""
 }
 
 func requireAnthropicAPIKey() string {
 	if k := anthropicAPIKey(); k != "" {
 		return k
 	}
-	fmt.Fprintln(os.Stderr, "error: set ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN")
+	fmt.Fprintln(os.Stderr, "error: set ANTHROPIC_API_KEY, GEMINI_API_KEY, or OPENAI_API_KEY")
 	os.Exit(2)
 	return ""
 }
diff --git a/cmd/ukc-agent/exec.go b/cmd/ukc-agent/exec.go
index c055442..b9cb335 100644
--- a/cmd/ukc-agent/exec.go
+++ b/cmd/ukc-agent/exec.go
@@ -9,6 +9,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"os"
 	"os/exec"
 	"sync"
 	"time"
@@ -65,7 +66,11 @@ func (jr *jobRunner) runCommand(parent context.Context, j *job, command string)
 	defer cancel()
 
 	cmd := exec.CommandContext(ctx, "/bin/sh", "-c", command)
-	cmd.Dir = "/workspace"
+	if dir := os.Getenv("UKC_AGENT_WORKSPACE"); dir != "" {
+		cmd.Dir = dir
+	} else {
+		cmd.Dir = "/workspace"
+	}
 	stdout, err := cmd.StdoutPipe()
 	if err != nil {
 		j.emitThenClose(err.Error(), 1)
diff --git a/cmd/ukc-agent/exec_test.go b/cmd/ukc-agent/exec_test.go
new file mode 100644
index 0000000..63bc358
--- /dev/null
+++ b/cmd/ukc-agent/exec_test.go
@@ -0,0 +1,112 @@
+package main
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestStreamReplay_LastEventID(t *testing.T) {
+	jr := newJobRunner("")
+	id := randomID()
+	
+	// Create a dummy job with history
+	j := &job{
+		id:        id,
+		history:   make([]map[string]any, 0, 64),
+		listeners: make([]chan struct{}, 0),
+	}
+	jr.jobs[id] = j
+	
+	j.trySend(map[string]any{"line": "hello"})
+	j.trySend(map[string]any{"line": "world"})
+	j.trySend(map[string]any{"done": true, "exit_code": 0})
+
+	// Test requesting from event 1 (skipping "hello", fetching "world" and "done")
+	req := httptest.NewRequest(http.MethodGet, "/stream", nil)
+	req.Header.Set("Last-Event-ID", "0")
+	rec := httptest.NewRecorder()
+
+	err := jr.streamSSE(rec, req, id)
+	if err != nil {
+		t.Fatalf("streamSSE error: %v", err)
+	}
+
+	out := rec.Body.String()
+	if strings.Contains(out, "hello") {
+		t.Fatalf("expected hello to be skipped, got: %s", out)
+	}
+	if !strings.Contains(out, "world") {
+		t.Fatalf("expected world, got: %s", out)
+	}
+}
+
+func TestStreamReplay_GapWarning(t *testing.T) {
+	jr := newJobRunner("")
+	id := randomID()
+	
+	j := &job{
+		id:        id,
+		history:   make([]map[string]any, 0, 64),
+		listeners: make([]chan struct{}, 0),
+		baseIndex: 50, // simulate that events 0-49 were evicted
+	}
+	jr.jobs[id] = j
+	
+	j.trySend(map[string]any{"line": "late event"})
+	j.trySend(map[string]any{"done": true, "exit_code": 0})
+
+	// Requesting from event 0, but base is 50, so gap warning should be emitted
+	req := httptest.NewRequest(http.MethodGet, "/stream", nil)
+	req.Header.Set("Last-Event-ID", "0")
+	rec := httptest.NewRecorder()
+
+	err := jr.streamSSE(rec, req, id)
+	if err != nil {
+		t.Fatalf("streamSSE error: %v", err)
+	}
+
+	out := rec.Body.String()
+	if !strings.Contains(out, "stream replay gap") {
+		t.Fatalf("expected gap warning, got: %s", out)
+	}
+	if !strings.Contains(out, "late event") {
+		t.Fatalf("expected late event, got: %s", out)
+	}
+}
+
+func TestStreamReplay_LiveReconnection(t *testing.T) {
+	jr := newJobRunner("")
+	tmpDir := t.TempDir()
+	t.Setenv("UKC_AGENT_WORKSPACE", tmpDir)
+	id := jr.start(context.Background(), "echo 'first'; sleep 0.1; echo 'second'")
+
+	// First connection: read "first", then disconnect
+	ctx, cancel1 := context.WithCancel(context.Background())
+	req1, _ := http.NewRequestWithContext(ctx, http.MethodGet, "/stream", nil)
+	rec1 := httptest.NewRecorder()
+	
+	// We want to stream until we see "first", then cancel the context to simulate disconnect
+	go func() {
+		// Read body manually instead of streamSSE to interleave properly
+		time.Sleep(50 * time.Millisecond)
+		cancel1()
+	}()
+	
+	_ = jr.streamSSE(rec1, req1, id) // this will return context.Canceled
+
+	// Second connection: read the rest
+	req2 := httptest.NewRequest(http.MethodGet, "/stream", nil)
+	rec2 := httptest.NewRecorder()
+	_ = jr.streamSSE(rec2, req2, id)
+
+	out := rec2.Body.String()
+	
+	// We might get "first" again if we didn't use Last-Event-ID, but we should definitely get "second"
+	if !strings.Contains(out, "second") {
+		t.Fatalf("expected second to arrive in the stream: %s", out)
+	}
+}
diff --git a/design/01-foundation.md b/docs/adr/01-foundation.md
similarity index 100%
rename from design/01-foundation.md
rename to docs/adr/01-foundation.md
diff --git a/design/02-agent-loop.md b/docs/adr/02-agent-loop.md
similarity index 100%
rename from design/02-agent-loop.md
rename to docs/adr/02-agent-loop.md
diff --git a/design/03-tools-overview.md b/docs/adr/03-tools-overview.md
similarity index 100%
rename from design/03-tools-overview.md
rename to docs/adr/03-tools-overview.md
diff --git a/design/04-fs-tools.md b/docs/adr/04-fs-tools.md
similarity index 100%
rename from design/04-fs-tools.md
rename to docs/adr/04-fs-tools.md
diff --git a/design/05-shell-search-tools.md b/docs/adr/05-shell-search-tools.md
similarity index 100%
rename from design/05-shell-search-tools.md
rename to docs/adr/05-shell-search-tools.md
diff --git a/design/06-git-web-tools.md b/docs/adr/06-git-web-tools.md
similarity index 100%
rename from design/06-git-web-tools.md
rename to docs/adr/06-git-web-tools.md
diff --git a/design/07-tui.md b/docs/adr/07-tui.md
similarity index 100%
rename from design/07-tui.md
rename to docs/adr/07-tui.md
diff --git a/design/08-config-permissions-undercover.md b/docs/adr/08-config-permissions-undercover.md
similarity index 100%
rename from design/08-config-permissions-undercover.md
rename to docs/adr/08-config-permissions-undercover.md
diff --git a/design/09-advanced-systems.md b/docs/adr/09-advanced-systems.md
similarity index 100%
rename from design/09-advanced-systems.md
rename to docs/adr/09-advanced-systems.md
diff --git a/design/10-integrations.md b/docs/adr/10-integrations.md
similarity index 100%
rename from design/10-integrations.md
rename to docs/adr/10-integrations.md
diff --git a/design/11-headless-orchestration.md b/docs/adr/11-headless-orchestration.md
similarity index 100%
rename from design/11-headless-orchestration.md
rename to docs/adr/11-headless-orchestration.md
diff --git a/design/12-property-fuzz-testing.md b/docs/adr/12-property-fuzz-testing.md
similarity index 100%
rename from design/12-property-fuzz-testing.md
rename to docs/adr/12-property-fuzz-testing.md
diff --git a/design/13-test-coverage-plan.md b/docs/adr/13-test-coverage-plan.md
similarity index 100%
rename from design/13-test-coverage-plan.md
rename to docs/adr/13-test-coverage-plan.md
diff --git a/design/14-ux-memory-improvements.md b/docs/adr/14-ux-memory-improvements.md
similarity index 100%
rename from design/14-ux-memory-improvements.md
rename to docs/adr/14-ux-memory-improvements.md
diff --git a/design/15-ukc-tools.md b/docs/adr/15-ukc-tools.md
similarity index 100%
rename from design/15-ukc-tools.md
rename to docs/adr/15-ukc-tools.md
diff --git a/design/16-ukc-workspace-sync.md b/docs/adr/16-ukc-workspace-sync.md
similarity index 100%
rename from design/16-ukc-workspace-sync.md
rename to docs/adr/16-ukc-workspace-sync.md
diff --git a/design/17-custom-commands.md b/docs/adr/17-custom-commands.md
similarity index 100%
rename from design/17-custom-commands.md
rename to docs/adr/17-custom-commands.md
diff --git a/design/18-tui-roadmap.md b/docs/adr/18-tui-roadmap.md
similarity index 100%
rename from design/18-tui-roadmap.md
rename to docs/adr/18-tui-roadmap.md
diff --git a/design/19-tui-test-strategy.md b/docs/adr/19-tui-test-strategy.md
similarity index 100%
rename from design/19-tui-test-strategy.md
rename to docs/adr/19-tui-test-strategy.md
diff --git a/design/claude-go-design-spec.md b/docs/adr/claude-go-design-spec.md
similarity index 100%
rename from design/claude-go-design-spec.md
rename to docs/adr/claude-go-design-spec.md
diff --git a/design/claude-go-test-spec.md b/docs/adr/claude-go-test-spec.md
similarity index 100%
rename from design/claude-go-test-spec.md
rename to docs/adr/claude-go-test-spec.md
diff --git a/docs/how-to/configure-custom-providers.md b/docs/how-to/configure-custom-providers.md
index 3367e0d..9801452 100644
--- a/docs/how-to/configure-custom-providers.md
+++ b/docs/how-to/configure-custom-providers.md
@@ -17,12 +17,7 @@ Official Anthropic needs only `ANTHROPIC_API_KEY` (default base URL is `https://
 
 ## Environment variables
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `ANTHROPIC_API_KEY` | One of key vars | Primary API key (Anthropic `sk-ant-…` or a provider key). |
-| `ANTHROPIC_AUTH_TOKEN` | One of key vars | Alternative key name; **if `ANTHROPIC_API_KEY` is empty, this is used** (e.g. Moonshot/Kimi docs). |
-| `ANTHROPIC_BASE_URL` | For gateways | Overrides the API host. Requests go to `{BASE_URL}/v1/messages` (no trailing slash required). |
-| `ANTHROPIC_MODEL` | Optional | Model id for the provider (also configurable via `.claude/settings.json` `"model"`). |
+To configure custom endpoints, you will need to set the appropriate environment variables. For a complete list of accepted variables (such as `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY`), please refer to the [Environment Variables Reference](../reference/environment-variables.md).
 
 At least one of `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` must be non-empty.
 
diff --git a/docs/reference/agent-context.md b/docs/reference/agent-context.md
new file mode 100644
index 0000000..f496b69
--- /dev/null
+++ b/docs/reference/agent-context.md
@@ -0,0 +1,66 @@
+---
+title: Agent Context
+description: Reference for AI coding assistants to understand the structure, context, and conventions of the drover-code repository.
+product: drover-code
+audience: agent
+doc_type: reference
+surface: repo-docs
+---
+
+# Agent Context for Drover Code
+
+Welcome, AI Agent. This file is intended to help AI coding assistants understand the structure, context, and conventions of the `drover-code` repository.
+
+## Ecosystem Role
+
+> **Part of the Drover Ecosystem**: `drover-code` serves as the **Core Agent Engine**. It is the fast, static Go binary that actually runs the agentic loop, calls the Anthropic API (via `drover-gateway`), and executes tools. It is orchestrated by `drover` and runs headlessly inside `drover-cloud` unikernels.
+
+## What this repo is
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `cmd/drover-code` | CLI entry: TUI, headless, `webhook`, flags |
+| `cmd/ukc-agent` | HTTP agent for Unikraft Cloud instances (workspace sync & exec) |
+| `internal/agent` | Agent loop, events |
+| `internal/api` | HTTP client, SSE stream |
+| `internal/bridge` | IDE bridge (JSON-RPC framing over stdio) |
+| `internal/config` | Settings merge, `CLAUDE.md` / markdown injection |
+| `internal/integrations/sqlforge` | Detect `sqlforge.yml`; inject SQLForge CLI guidance |
+| `internal/convo` | Conversation state, compaction heuristics |
+| `internal/coordinator` | Multi-worker coordinator mode |
+| `internal/github` | Webhook server, parser, runner |
+| `internal/tools` | Tool registry and implementations |
+| `internal/tui` | Bubble Tea model and views |
+| `internal/dream` | Session memory (JSON / SQLite) |
+| `design/` | Design specs and roadmap (numbered `01-…`, test plan `13`, UX `14`) |
+| `docs/` | User-facing docs (Tutorials, How-Tos, Reference, Explanation) |
+
+## Build and test
+
+```bash
+CGO_ENABLED=0 go build -o drover-code ./cmd/drover-code
+CGO_ENABLED=0 go build -o ukc-agent ./cmd/ukc-agent
+CGO_ENABLED=0 go test ./...
+```
+
+CI uses Go 1.22 with `CGO_ENABLED=0`. Local `go.mod` may list a newer `go` directive; keep changes compatible with CI unless you bump the workflow.
+
+Fuzz targets are listed in `.github/workflows/ci.yml` (`fuzz` job).
+
+## Conventions
+
+- Prefer focused changes: match existing style, imports, and error wrapping in touched packages.
+- Property / fuzz tests: see `design/12-property-fuzz-testing.md` and doc `13-test-coverage-plan.md`.
+- Do not assume Node: this is Go-only for the main binary.
+
+## Product behavior pointers
+
+- End-user overview, env vars, and modes: `README.md`.
+- `internal/config` walks upward from `workDir` and merges `CLAUDE.md` files into the system prompt. If this repository is the working directory, **this** `CLAUDE.md` is included like any other project instructions file.
+- When `sqlforge.yml` is found at a project root, SQLForge CLI guidance is appended automatically. How-to: `docs/how-to/sqlforge-from-drover-code.md`.
+
+## Optional evals
+
+Live Anthropic eval tests are opt-in (`RUN_AGENT_EVALS=1` and API key); see `evals/` and `README.md`.
diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md
new file mode 100644
index 0000000..25f12c7
--- /dev/null
+++ b/docs/reference/environment-variables.md
@@ -0,0 +1,65 @@
+---
+title: Environment Variables
+description: Comprehensive reference of all environment variables used to configure Drover Code.
+product: drover-code
+audience: platform-operator
+doc_type: reference
+surface: repo-docs
+---
+
+# Environment Variables Reference
+
+`drover-code` is highly configurable via environment variables. This reference documents all available variables, their purpose, and their acceptable values.
+
+## Anthropic / API Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ANTHROPIC_API_KEY` | One of key vars | Primary API key (Anthropic `sk-ant-…` or a provider key). |
+| `ANTHROPIC_AUTH_TOKEN` | One of key vars | Alternative key name; **if `ANTHROPIC_API_KEY` is empty, this is used** (e.g. Moonshot/Kimi docs). |
+| `ANTHROPIC_BASE_URL` | For gateways | Overrides the API host. Requests go to `{BASE_URL}/v1/messages` (no trailing slash required). |
+| `ANTHROPIC_MODEL` | Optional | Model id for the provider (also configurable via `.drover/settings.json` `"model"`). |
+
+At least one of `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` must be non-empty to run the agent.
+
+## Headless & Coordinator Modes
+
+| Variable | Description |
+|----------|-------------|
+| `DROVER_CODE_HEADLESS` | Set to `1` to run in non-interactive batch worker mode (no TTY, no prompts). |
+| `DROVER_CODE_HEADLESS_PLAIN` | Set to `1` to force plain text output instead of default headless formatting. |
+| `DROVER_CODE_JSONL` | Set to `1` to force JSON Lines event output in headless mode. |
+| `DROVER_CODE_RESULT_PATH` | Path to write the final structured completion artifact on exit. |
+| `CLAUDE_CODE_COORDINATOR_MODE`| Set to `1` to run as a multi-worker task coordinator. |
+| `CLAUDE_CODE_IDE_BRIDGE` | Set to `1` to run as a JSON-RPC over stdio backend. |
+
+## Permission & Governance
+
+| Variable | Description |
+|----------|-------------|
+| `DROVER_CODE_PERMISSION_PRESET`| Preset rules for tool execution (e.g., `unikernel` for isolated workers). |
+| `DROVER_WARDEN_BEADS_DIR` | Directory containing `policies.jsonl` and `audit.jsonl` for the Warden semantic firewall. |
+
+## Dream Memory Backend
+
+| Variable | Description |
+|----------|-------------|
+| `DROVER_CODE_DREAM_BACKEND` | Storage backend for memory. Set to `sqlite` for database-backed storage (`.drover/memory.db`). Defaults to JSON. |
+| `DROVER_CODE_DREAM_SKIP_JSON_IMPORT`| Set to `1` to skip importing existing `memory.json` on first SQLite init. |
+| `DROVER_CODE_DREAM_MAX_ENTRIES`| Maximum number of memory rows to retain (newest first). |
+| `DROVER_CODE_DREAM_MAX_AGE_DAYS`| Maximum age of memory entries in days. |
+
+## Webhook Mode
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_TOKEN` | Required for `./drover-code webhook`. API token for interacting with GitHub. |
+| `GITHUB_WEBHOOK_SECRET` | Secret for verifying HMAC signatures on inbound GitHub webhooks. |
+| `WEBHOOK_ADDR` | Listen address for the webhook server (e.g., `:8080`). |
+| `WEBHOOK_WORK_DIR` | Working directory for the agent sessions spawned by webhooks. |
+
+## Evals
+
+| Variable | Description |
+|----------|-------------|
+| `RUN_AGENT_EVALS` | Set to `1` to enable live Anthropic eval tests during `go test ./evals/...`. |
diff --git a/go.mod b/go.mod
index a3dbb68..97296c3 100644
--- a/go.mod
+++ b/go.mod
@@ -86,4 +86,5 @@ require (
 	modernc.org/libc v1.61.13 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.8.2 // indirect
+	pgregory.net/rapid v1.3.0 // indirect
 )
diff --git a/go.sum b/go.sum
index fda341f..76a0bb1 100644
--- a/go.sum
+++ b/go.sum
@@ -285,3 +285,5 @@ modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
 modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
 modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
 modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
+pgregory.net/rapid v1.3.0 h1:vBvO0VSqti75J1jjYqpgPNBLKMd1+gxa9fYo7vk/Exc=
+pgregory.net/rapid v1.3.0/go.mod h1:dPlE4OBBxgXPqkP79flB6sJL1dx5azpI7HQ9MY9Z7uk=
diff --git a/internal/bridge/bridge.go b/internal/bridge/bridge.go
index 3ea0abd..4530c69 100644
--- a/internal/bridge/bridge.go
+++ b/internal/bridge/bridge.go
@@ -192,6 +192,10 @@ func (b *Bridge) readMessageSync() (Message, error) {
 		return Message{}, fmt.Errorf("missing Content-Length")
 	}
 
+	if contentLength > 32*1024*1024 { // 32 MiB limit
+		return Message{}, fmt.Errorf("message too large: %d bytes exceeds 32MiB limit", contentLength)
+	}
+
 	body := make([]byte, contentLength)
 	if _, err := io.ReadFull(b.r, body); err != nil {
 		return Message{}, fmt.Errorf("read body: %w", err)
diff --git a/internal/bridge/bridge_test.go b/internal/bridge/bridge_test.go
index d9f27e4..e858ff3 100644
--- a/internal/bridge/bridge_test.go
+++ b/internal/bridge/bridge_test.go
@@ -176,6 +176,20 @@ func TestBridge_readMessage_badJSONBody(t *testing.T) {
 	}
 }
 
+func TestBridge_readMessage_oversizedBody(t *testing.T) {
+	// Requesting an allocation larger than 32 MiB without actually sending that much data.
+	in := "Content-Length: 33554433\r\n\r\n"
+	var out bytes.Buffer
+	b := NewBridge(strings.NewReader(in), &out)
+	_, err := b.readMessage(context.Background())
+	if err == nil {
+		t.Fatal("expected error for oversized body")
+	}
+	if !strings.Contains(err.Error(), "exceeds 32MiB limit") {
+		t.Fatalf("expected 32MiB limit error, got: %v", err)
+	}
+}
+
 func TestBridge_readMessageParsesFramedJSON(t *testing.T) {
 	msg := `{"jsonrpc":"2.0","id":1,"method":"ping","params":{"a":1}}`
 	in := "Content-Length: " + itoa(len([]byte(msg))) + "\r\n\r\n" + msg
diff --git a/internal/config/loader.go b/internal/config/loader.go
index ae5db03..3fdb41e 100644
--- a/internal/config/loader.go
+++ b/internal/config/loader.go
@@ -1,6 +1,9 @@
 // Package config loads and merges drover-code settings from the three-level
-// hierarchy: global (~/.claude/settings.json) → project (.claude/settings.json)
-// → local (.claude/settings.local.json).
+// hierarchy: global (~/.drover/settings.json) → project (.drover/settings.json)
+// → local (.drover/settings.local.json).
+//
+// Legacy Claude Code paths (~/.claude and .claude at each level) are still read
+// when present; drover paths override claude paths at the same tier.
 //
 // It also walks the directory tree for CLAUDE.md files and concatenates them
 // into a system-prompt injection.
@@ -69,8 +72,19 @@ func NewLoader(workDir string) *Loader {
 	home, _ := os.UserHomeDir()
 	return &Loader{
 		workDir:    workDir,
-		globalDir:  filepath.Join(home, ".claude"),
-		projectDir: filepath.Join(workDir, ".claude"),
+		globalDir:  filepath.Join(home, ".drover"),
+		projectDir: filepath.Join(workDir, ".drover"),
+	}
+}
+
+func settingsLoadPaths(home, workDir string) []string {
+	return []string{
+		filepath.Join(home, ".claude", "settings.json"),
+		filepath.Join(home, ".drover", "settings.json"),
+		filepath.Join(workDir, ".claude", "settings.json"),
+		filepath.Join(workDir, ".drover", "settings.json"),
+		filepath.Join(workDir, ".claude", "settings.local.json"),
+		filepath.Join(workDir, ".drover", "settings.local.json"),
 	}
 }
 
@@ -80,11 +94,8 @@ func (l *Loader) Load() error {
 	defer l.mu.Unlock()
 
 	var merged Settings
-	paths := []string{
-		filepath.Join(l.globalDir, "settings.json"),
-		filepath.Join(l.projectDir, "settings.json"),
-		filepath.Join(l.projectDir, "settings.local.json"),
-	}
+	home, _ := os.UserHomeDir()
+	paths := settingsLoadPaths(home, l.workDir)
 
 	for _, p := range paths {
 		data, err := os.ReadFile(p)
diff --git a/internal/config/loader_test.go b/internal/config/loader_test.go
index d99ff09..f9a271c 100644
--- a/internal/config/loader_test.go
+++ b/internal/config/loader_test.go
@@ -12,20 +12,20 @@ func TestLoader_MergeOrder_ProjectWins(t *testing.T) {
 	t.Setenv("HOME", home)
 
 	proj := filepath.Join(home, "proj")
-	if err := os.MkdirAll(filepath.Join(proj, ".claude"), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Join(proj, ".drover"), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.MkdirAll(filepath.Join(home, ".claude"), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Join(home, ".drover"), 0o755); err != nil {
 		t.Fatal(err)
 	}
 
-	if err := os.WriteFile(filepath.Join(home, ".claude", "settings.json"), []byte(`{"model":"global-m","permissionMode":"default","dreamEnabled":false}`), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(home, ".drover", "settings.json"), []byte(`{"model":"global-m","permissionMode":"default","dreamEnabled":false}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(proj, ".claude", "settings.json"), []byte(`{"model":"proj-m","dreamEnabled":true}`), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(proj, ".drover", "settings.json"), []byte(`{"model":"proj-m","dreamEnabled":true}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(proj, ".claude", "settings.local.json"), []byte(`{"model":"local-m","env":{"FOO":"bar"}}`), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(proj, ".drover", "settings.local.json"), []byte(`{"model":"local-m","env":{"FOO":"bar"}}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
 
@@ -45,20 +45,68 @@ func TestLoader_MergeOrder_ProjectWins(t *testing.T) {
 	}
 }
 
-func TestLoader_DreamRetentionMerge(t *testing.T) {
+func TestLoader_LegacyClaudePathsStillLoad(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+
+	proj := filepath.Join(home, "proj")
+	if err := os.MkdirAll(filepath.Join(proj, ".claude"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(proj, ".claude", "settings.json"), []byte(`{"model":"legacy-m"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	l := NewLoader(proj)
+	if err := l.Load(); err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if got := l.Get().Model; got != "legacy-m" {
+		t.Fatalf("model: got %q want legacy-m", got)
+	}
+}
+
+func TestLoader_DroverOverridesLegacyClaudeAtSameTier(t *testing.T) {
 	home := t.TempDir()
 	t.Setenv("HOME", home)
+
 	proj := filepath.Join(home, "proj")
 	if err := os.MkdirAll(filepath.Join(proj, ".claude"), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.MkdirAll(filepath.Join(home, ".claude"), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Join(proj, ".drover"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(proj, ".claude", "settings.json"), []byte(`{"model":"legacy-m"}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(home, ".claude", "settings.json"), []byte(`{"dreamMaxRetentionEntries":1000}`), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(proj, ".drover", "settings.json"), []byte(`{"model":"drover-m"}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(proj, ".claude", "settings.json"), []byte(`{"dreamMaxRetentionEntries":40,"dreamMaxRetentionAgeDays":90}`), 0o644); err != nil {
+
+	l := NewLoader(proj)
+	if err := l.Load(); err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if got := l.Get().Model; got != "drover-m" {
+		t.Fatalf("model: got %q want drover-m", got)
+	}
+}
+
+func TestLoader_DreamRetentionMerge(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	proj := filepath.Join(home, "proj")
+	if err := os.MkdirAll(filepath.Join(proj, ".drover"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(home, ".drover"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(home, ".drover", "settings.json"), []byte(`{"dreamMaxRetentionEntries":1000}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(proj, ".drover", "settings.json"), []byte(`{"dreamMaxRetentionEntries":40,"dreamMaxRetentionAgeDays":90}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	l := NewLoader(proj)
@@ -93,10 +141,10 @@ func TestLoader_ProjectMarkdownIgnoreGlobs(t *testing.T) {
 	if err := os.WriteFile(filepath.Join(proj, "CLAUDE.md"), []byte("root"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.MkdirAll(filepath.Join(proj, ".claude"), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Join(proj, ".drover"), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(proj, ".claude", "settings.json"), []byte(`{"projectMarkdownIgnoreGlobs":["vendor/**"]}`), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(proj, ".drover", "settings.json"), []byte(`{"projectMarkdownIgnoreGlobs":["vendor/**"]}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
 
@@ -148,10 +196,10 @@ func TestLoader_ProjectMarkdownByteCap(t *testing.T) {
 	t.Setenv("HOME", home)
 
 	proj := filepath.Join(home, "proj")
-	if err := os.MkdirAll(filepath.Join(proj, ".claude"), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Join(proj, ".drover"), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(proj, ".claude", "settings.json"), []byte(`{"projectMarkdownMaxBytes":800}`), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(proj, ".drover", "settings.json"), []byte(`{"projectMarkdownMaxBytes":800}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	if err := os.WriteFile(filepath.Join(proj, "CLAUDE.md"), []byte(strings.Repeat("x", 5000)), 0o644); err != nil {
@@ -173,10 +221,10 @@ func TestLoader_ProjectMarkdownByteCap(t *testing.T) {
 
 func TestLoader_Save_MergesProjectFile(t *testing.T) {
 	proj := t.TempDir()
-	if err := os.MkdirAll(filepath.Join(proj, ".claude"), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Join(proj, ".drover"), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(proj, ".claude", "settings.json"), []byte(`{"model":"old"}`), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(proj, ".drover", "settings.json"), []byte(`{"model":"old"}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
 
@@ -187,6 +235,9 @@ func TestLoader_Save_MergesProjectFile(t *testing.T) {
 	if err := l.Save(Settings{MaxTokens: 4096}); err != nil {
 		t.Fatalf("Save: %v", err)
 	}
+	if _, err := os.Stat(filepath.Join(proj, ".drover", "settings.json")); err != nil {
+		t.Fatalf("Save should write .drover/settings.json: %v", err)
+	}
 	if err := l.Load(); err != nil {
 		t.Fatal(err)
 	}
diff --git a/internal/config/sqlforge_injection_test.go b/internal/config/sqlforge_injection_test.go
index 6b97edb..206130a 100644
--- a/internal/config/sqlforge_injection_test.go
+++ b/internal/config/sqlforge_injection_test.go
@@ -12,10 +12,10 @@ func TestLoadInjectsSQLForgeGuidance(t *testing.T) {
 	if err := os.WriteFile(filepath.Join(proj, "sqlforge.yml"), []byte("default_environment: dev\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.MkdirAll(filepath.Join(proj, ".claude"), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Join(proj, ".drover"), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(proj, ".claude", "settings.json"), []byte(`{}`), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(proj, ".drover", "settings.json"), []byte(`{}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
 
diff --git a/internal/convo/convo_property_test.go b/internal/convo/convo_property_test.go
index 573e812..ffc0375 100644
--- a/internal/convo/convo_property_test.go
+++ b/internal/convo/convo_property_test.go
@@ -3,13 +3,16 @@ package convo
 import (
 	"fmt"
 	"testing"
-	"testing/quick"
 
 	"github.com/cloudshuttle/drover-code/internal/api"
+	"pgregory.net/rapid"
 )
 
 func TestProperty_EstimatedTokensNonNegative(t *testing.T) {
-	err := quick.Check(func(sys, body string) bool {
+	rapid.Check(t, func(t *rapid.T) {
+		sys := rapid.String().Draw(t, "sys")
+		body := rapid.String().Draw(t, "body")
+
 		m := NewManagerWithSystem(sys)
 		m.Append(api.UserMessage(body))
 		m.Append(api.AssistantMessage([]api.ContentBlock{
@@ -19,60 +22,80 @@ func TestProperty_EstimatedTokensNonNegative(t *testing.T) {
 		m.Append(api.ToolResultMessage([]api.ToolResultBlock{
 			{ToolUseID: "x", Content: body},
 		}))
-		return m.EstimatedTokens() >= 0
-	}, &quick.Config{MaxCount: 200})
-	if err != nil {
-		t.Fatal(err)
-	}
+
+		if m.EstimatedTokens() < 0 {
+			t.Fatalf("EstimatedTokens should be non-negative, got: %d", m.EstimatedTokens())
+		}
+	})
 }
 
 func TestProperty_SummariseMessageCount(t *testing.T) {
-	err := quick.Check(func(n, k byte, summary string) bool {
-		count := int(n%30) + 1
-		keep := int(k % 30)
+	rapid.Check(t, func(t *rapid.T) {
+		count := rapid.IntRange(1, 30).Draw(t, "count")
+		keep := rapid.IntRange(0, 30).Draw(t, "keep")
+		summary := rapid.String().Draw(t, "summary")
+
 		m := NewManager()
 		for i := 0; i < count; i++ {
 			m.Append(api.UserMessage(fmt.Sprintf("m%d", i)))
 		}
+
 		before := len(m.Messages())
 		m.Summarise(summary, keep)
 		after := len(m.Messages())
+
 		if before <= keep {
-			return after == before
+			if after != before {
+				t.Fatalf("Expected %d messages after keeping %d (from %d), but got %d", before, keep, before, after)
+			}
+		} else {
+			if after != keep+1 {
+				t.Fatalf("Expected %d messages after summarising to keep %d, but got %d", keep+1, keep, after)
+			}
 		}
-		return after == keep+1
-	}, &quick.Config{MaxCount: 200})
-	if err != nil {
-		t.Fatal(err)
-	}
+	})
 }
 
 func TestProperty_SetContextLimitPositiveOnly(t *testing.T) {
-	err := quick.Check(func(limit int, sys string) bool {
+	rapid.Check(t, func(t *rapid.T) {
+		limit := rapid.Int().Draw(t, "limit")
+		sys := rapid.String().Draw(t, "sys")
+
 		m := NewManagerWithSystem(sys)
 		prev := m.ContextLimit()
 		m.SetContextLimit(limit)
 		got := m.ContextLimit()
+
 		if limit > 0 {
-			return got == limit
+			if got != limit {
+				t.Fatalf("Expected limit to be updated to %d, got %d", limit, got)
+			}
+		} else {
+			if got != prev {
+				t.Fatalf("Expected limit to remain %d when setting negative limit %d, got %d", prev, limit, got)
+			}
 		}
-		return got == prev
-	}, &quick.Config{MaxCount: 150})
-	if err != nil {
-		t.Fatal(err)
-	}
+	})
 }
 
 func TestProperty_ResetClearsHistory(t *testing.T) {
-	err := quick.Check(func(n byte, s string) bool {
+	rapid.Check(t, func(t *rapid.T) {
+		n := rapid.IntRange(0, 50).Draw(t, "n")
+		s := rapid.String().Draw(t, "s")
+
 		m := NewManagerWithSystem(s)
-		for i := 0; i < int(n%50); i++ {
+		for i := 0; i < n; i++ {
 			m.Append(api.UserMessage(fmt.Sprintf("x%d", i)))
 		}
+
 		m.Reset()
-		return len(m.Messages()) == 0 && m.SystemPrompt() == s
-	}, &quick.Config{MaxCount: 150})
-	if err != nil {
-		t.Fatal(err)
-	}
+
+		if len(m.Messages()) != 0 {
+			t.Fatalf("Expected 0 messages after reset, got %d", len(m.Messages()))
+		}
+		if m.SystemPrompt() != s {
+			t.Fatalf("Expected system prompt to remain %q, got %q", s, m.SystemPrompt())
+		}
+	})
 }
+
diff --git a/internal/coordinator/coordinator.go b/internal/coordinator/coordinator.go
index 89eb06f..57faa88 100644
--- a/internal/coordinator/coordinator.go
+++ b/internal/coordinator/coordinator.go
@@ -23,7 +23,8 @@ import (
 	"github.com/cloudshuttle/drover-code/internal/permissions"
 	"github.com/cloudshuttle/drover-code/internal/tools"
 	"github.com/cloudshuttle/drover-code/internal/tools/ukc"
-	"github.com/cloudshuttle/drover-code/internal/workerclient"
+	"github.com/cloudshuttle/drover-code/pkg/workercontract/client"
+	"github.com/cloudshuttle/drover-code/pkg/workercontract/workspace"
 )
 
 const maxCoordinatorSubtasks = 8
@@ -340,17 +341,11 @@ func (c *Coordinator) runWorkerRemote(ctx context.Context, st Subtask, customIma
 	}
 
 	name := fmt.Sprintf("drover-worker-%d-%d", st.Index, time.Now().Unix())
-	c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] Provisioning UKC instance %s...\n", st.Index+1, name)}
-
-	// Create instance
-	token, _ := ukc.RandToken()
-	cfg := mgr.Config()
+	
 	env := map[string]string{
-		"AGENT_TOKEN":                  token,
 		"DROVER_CODE_HEADLESS":         "1",
 		"DROVER_CODE_PERMISSION_PRESET": "unikernel",
 	}
-	// Forward LLM API keys and configuration to the remote workers
 	for _, k := range []string{
 		"ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY",
 		"ANTHROPIC_MODEL", "OPENAI_MODEL", "GEMINI_MODEL",
@@ -360,74 +355,13 @@ func (c *Coordinator) runWorkerRemote(ctx context.Context, st Subtask, customIma
 		}
 	}
 
-	img := cfg.DefaultImage
+	img := mgr.Config().DefaultImage
 	if customImage != "" {
 		img = customImage
 	}
 
-	inst, err := ukc.CreateInstance(ctx, cfg, name, img, 512, env)
-	if err != nil {
-		return WorkerResult{Index: st.Index, Task: st.Description, IsError: true, Output: err.Error()}, err
-	}
-
-	// Fetch the complete Service Group object to get the Domains if they aren't included inline
-	if inst.ServiceGroup != nil && inst.ServiceGroup.UUID != "" && len(inst.ServiceGroup.Domains) == 0 {
-		sg, err := ukc.GetServiceGroup(ctx, cfg, inst.ServiceGroup.UUID)
-		if err == nil {
-			inst.ServiceGroup = &sg
-		} else {
-			return WorkerResult{Index: st.Index, Task: st.Description, IsError: true, Output: "failed to get service group: " + err.Error()}, err
-		}
-	}
-
-	instURL := ukc.InstanceHTTPSURL(inst)
-	if instURL == "" {
-		// Cleanup the instance if we couldn't get a URL
-		_ = ukc.DeleteInstance(context.Background(), cfg, inst.UUID)
-		return WorkerResult{Index: st.Index, Task: st.Description, IsError: true, Output: "Could not determine public HTTPS URL for Unikraft instance"}, fmt.Errorf("empty instance URL")
-	}
-
-	c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] Instance created, waiting for health check at %s...\n", st.Index+1, instURL)}
-
-	// Always cleanup worker instance (ADR 0003 instance lifecycle).
-	defer func() {
-		_ = ukc.UnregisterActiveJob(inst.UUID)
-		if err := ukc.DeleteInstance(context.Background(), cfg, inst.UUID); err != nil {
-			c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] ⚠️ Failed to destroy UKC instance %s: %v\n", st.Index+1, name, err)}
-		} else {
-			c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] Destroyed UKC instance %s\n", st.Index+1, name)}
-		}
-	}()
-	_ = ukc.RegisterActiveJob(inst.UUID, name)
-
-	wc := workerclient.New(instURL, token, cfg.HTTPClient)
-
-	if err := wc.WaitReady(ctx, cfg.MaxHealthWait); err != nil {
-		return WorkerResult{Index: st.Index, Task: st.Description, IsError: true, Output: "instance health timeout: " + err.Error()}, err
-	}
-
-	baseSHA, _ := gitHeadSHA(ctx, c.workDir)
-	if baseSHA != "" {
-		short := baseSHA
-		if len(short) > 8 {
-			short = short[:8]
-		}
-		c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] Base SHA: %s\n", st.Index+1, short)}
-	}
-
-	c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] Uploading local workspace to cloud instance...\n", st.Index+1)}
-	summary, err := ukc.PlanWorkspaceUpload(c.workDir, ukc.DefaultWorkspaceLimits())
-	if err != nil {
-		return WorkerResult{Index: st.Index, Task: st.Description, IsError: true, Output: "workspace plan: " + err.Error()}, err
-	}
-	if err := ukc.MaybeConfirmUpload(os.Stdin, os.Stdout, summary); err != nil {
-		return WorkerResult{Index: st.Index, Task: st.Description, IsError: true, Output: err.Error()}, err
-	}
-	if err := wc.UploadWorkspace(ctx, c.workDir, ukc.DefaultWorkspaceLimits()); err != nil {
-		return WorkerResult{Index: st.Index, Task: st.Description, IsError: true, Output: "upload workspace failed: " + err.Error()}, err
-	}
-
-	c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] Instance ready, executing headless task...\n", st.Index+1)}
+	downloadDir := filepath.Join(st.IsolatedDir, "workspace_downloaded")
+	_ = os.RemoveAll(downloadDir)
 
 	safeTask := strings.ReplaceAll(st.Description, "'", "'\\''")
 	command := fmt.Sprintf("drover-code --headless --prompt '%s'", safeTask)
@@ -450,38 +384,54 @@ func (c *Coordinator) runWorkerRemote(ctx context.Context, st Subtask, customIma
 			typ, _ := ev["type"].(string)
 			switch typ {
 			case "tool_start":
-				name, _ := ev["name"].(string)
-				c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("[worker %d] 🔨 using tool: %s\n", st.Index+1, name)}
+				toolName, _ := ev["name"].(string)
+				c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("[worker %d] 🔨 using tool: %s\n", st.Index+1, toolName)}
 			case "heartbeat":
 				turn, _ := ev["turn"].(float64)
 				c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("[worker %d] 🧠 thinking... (turn %d)\n", st.Index+1, int(turn))}
 			}
 		}
 	}
-	outStr, exitCode, err := wc.Exec(ctx, command, onLine)
+
+	baseSHA, _ := gitHeadSHA(ctx, c.workDir)
+	if baseSHA != "" {
+		short := baseSHA
+		if len(short) > 8 {
+			short = short[:8]
+		}
+		c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] Base SHA: %s\n", st.Index+1, short)}
+	}
+
+	res, err := client.RunAgentJob(ctx, mgr.Config(), client.JobSpec{
+		Name:         name,
+		Image:        img,
+		MemoryMB:     512,
+		Env:          env,
+		Command:      command,
+		WorkDir:      c.workDir,
+		DownloadDir:  downloadDir,
+		Limits:       workspace.DefaultLimits(),
+		OnEvent: func(msg string) {
+			c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] %s\n", st.Index+1, msg)}
+		},
+		OnStreamLine: onLine,
+	})
 
 	if err != nil {
 		return WorkerResult{Index: st.Index, Task: st.Description, IsError: true, Output: err.Error()}, err
 	}
-	if exitCode != 0 {
-		return WorkerResult{Index: st.Index, Task: st.Description, IsError: true, Output: outStr}, fmt.Errorf("remote task exited with %d", exitCode)
+	if res.ExitCode != 0 {
+		return WorkerResult{Index: st.Index, Task: st.Description, IsError: true, Output: res.Output}, fmt.Errorf("remote task exited with %d", res.ExitCode)
 	}
 
-	c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] Task complete. Downloading modified workspace...\n", st.Index+1)}
-	downloadDir := filepath.Join(st.IsolatedDir, "workspace_downloaded")
-	_ = os.RemoveAll(downloadDir)
-	if err := wc.DownloadWorkspace(ctx, downloadDir); err != nil {
-		c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] ⚠️ Failed to download workspace: %v\n", st.Index+1, err)}
-	} else {
-		if err := c.syncDownloadedWorkspace(ctx, st, downloadDir, baseSHA); err != nil {
-			c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] ⚠️ Failed to merge workspace: %v\n", st.Index+1, err)}
-		}
+	if err := c.syncDownloadedWorkspace(ctx, st, downloadDir, baseSHA); err != nil {
+		c.eventCh <- agent.TextDeltaEvent{Text: fmt.Sprintf("\n[worker %d] ⚠️ Failed to merge workspace: %v\n", st.Index+1, err)}
 	}
 
 	return WorkerResult{
 		Index:  st.Index,
 		Task:   st.Description,
-		Output: outStr,
+		Output: res.Output,
 	}, nil
 }
 
diff --git a/internal/dream/retention_test.go b/internal/dream/retention_test.go
index a209a6c..ba40f48 100644
--- a/internal/dream/retention_test.go
+++ b/internal/dream/retention_test.go
@@ -81,4 +81,33 @@ func TestRetention_ApplyEnvOverrides(t *testing.T) {
 	if r.MaxAgeDays != 0 {
 		t.Errorf("expected MaxAgeDays=0 for negative, got %d", r.MaxAgeDays)
 	}
+
+	t.Setenv("DROVER_CODE_DREAM_MAX_ENTRIES", "0")
+	t.Setenv("DROVER_CODE_DREAM_MAX_AGE_DAYS", "0")
+	
+	r = Retention{MaxEntries: 50, MaxAgeDays: 5} // start non-zero
+	r.ApplyEnvOverrides()
+	if r.MaxEntries != 0 {
+		t.Errorf("expected MaxEntries=0 when explicitly overriden to 0, got %d", r.MaxEntries)
+	}
+	if r.MaxAgeDays != 0 {
+		t.Errorf("expected MaxAgeDays=0 when explicitly overriden to 0, got %d", r.MaxAgeDays)
+	}
+}
+
+func TestRetention_Active(t *testing.T) {
+	r1 := Retention{MaxEntries: 0, MaxAgeDays: 0}
+	if r1.Active() {
+		t.Errorf("Retention{0,0} should not be active")
+	}
+
+	r2 := Retention{MaxEntries: 1, MaxAgeDays: 0}
+	if !r2.Active() {
+		t.Errorf("Retention{1,0} should be active")
+	}
+
+	r3 := Retention{MaxEntries: 0, MaxAgeDays: 1}
+	if !r3.Active() {
+		t.Errorf("Retention{0,1} should be active")
+	}
 }
diff --git a/internal/dream/sqlite_store_property_test.go b/internal/dream/sqlite_store_property_test.go
new file mode 100644
index 0000000..2c71a6d
--- /dev/null
+++ b/internal/dream/sqlite_store_property_test.go
@@ -0,0 +1,137 @@
+package dream
+
+import (
+	"fmt"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"pgregory.net/rapid"
+)
+
+// genEntry generates a random valid Entry.
+func genEntry() *rapid.Generator[Entry] {
+	return rapid.Custom(func(t *rapid.T) Entry {
+		// Use a large range of time, but not overflowing SQLite limits
+		ts := time.Unix(rapid.Int64Range(0, 253402300799).Draw(t, "ts"), 0).UTC()
+		return Entry{
+			ID:        rapid.String().Draw(t, "id"),
+			Timestamp: ts,
+			Tags:      rapid.SliceOf(rapid.String()).Draw(t, "tags"),
+			Content:   rapid.String().Draw(t, "content"),
+			SessionID: rapid.String().Draw(t, "session_id"),
+		}
+	})
+}
+
+func TestProperty_SQLitePruneLimits(t *testing.T) {
+	rapid.Check(t, func(rt *rapid.T) {
+		maxEntries := rapid.IntRange(0, 100).Draw(rt, "maxEntries")
+		maxAgeDays := rapid.IntRange(0, 365).Draw(rt, "maxAgeDays")
+
+		retention := Retention{
+			MaxEntries: maxEntries,
+			MaxAgeDays: maxAgeDays,
+		}
+
+		entries := rapid.SliceOfN(genEntry(), 0, 200).Draw(rt, "entries")
+
+		tmpDir := t.TempDir()
+		dbPath := filepath.Join(tmpDir, "memory.db")
+
+		store, err := NewSQLiteStore(dbPath)
+		if err != nil {
+			rt.Fatalf("Failed to create store: %v", err)
+		}
+
+		// Insert all entries
+		for i, e := range entries {
+			e.ID = fmt.Sprintf("id-%d", i)
+			if err := store.Save(e); err != nil {
+				rt.Fatalf("Failed to save entry: %v", err)
+			}
+		}
+
+		// Prune
+		if err := store.Prune(retention); err != nil {
+			rt.Fatalf("Failed to prune: %v", err)
+		}
+
+		// Load all entries back to check invariants
+		after, err := store.All()
+		if err != nil {
+			rt.Fatalf("Failed to get all entries: %v", err)
+		}
+
+		// Invariant 1: MaxEntries constraint
+		if retention.MaxEntries > 0 && len(after) > retention.MaxEntries {
+			rt.Fatalf("Store has %d entries, but MaxEntries is %d", len(after), retention.MaxEntries)
+		}
+
+		// Invariant 2: MaxAgeDays constraint
+		cutoff, hasAgeLimit := retention.minTimestamp()
+		if hasAgeLimit {
+			for _, e := range after {
+				if e.Timestamp.Before(cutoff) {
+					rt.Fatalf("Entry timestamp %v is older than cutoff %v", e.Timestamp, cutoff)
+				}
+			}
+		}
+		
+		store.(*sqliteStore).Close()
+	})
+}
+
+func TestProperty_SQLitePersistenceIntegrity(t *testing.T) {
+	rapid.Check(t, func(rt *rapid.T) {
+		entry := genEntry().Draw(rt, "entry")
+
+		tmpDir := t.TempDir()
+		dbPath := filepath.Join(tmpDir, "memory.db")
+
+		store, err := NewSQLiteStore(dbPath)
+		if err != nil {
+			rt.Fatalf("Failed to create store: %v", err)
+		}
+
+		if err := store.Save(entry); err != nil {
+			rt.Fatalf("Failed to save entry: %v", err)
+		}
+
+		after, err := store.All()
+		if err != nil {
+			rt.Fatalf("Failed to get all entries: %v", err)
+		}
+
+		if len(after) != 1 {
+			rt.Fatalf("Expected exactly 1 entry, got %d", len(after))
+		}
+
+		loaded := after[0]
+
+		if loaded.ID != entry.ID {
+			rt.Fatalf("ID mismatch: got %q, want %q", loaded.ID, entry.ID)
+		}
+		if loaded.Content != entry.Content {
+			rt.Fatalf("Content mismatch")
+		}
+		if loaded.SessionID != entry.SessionID {
+			rt.Fatalf("SessionID mismatch")
+		}
+		
+		if loaded.Timestamp.UnixNano() != entry.Timestamp.UnixNano() {
+			rt.Fatalf("Timestamp mismatch: got %v, want %v", loaded.Timestamp, entry.Timestamp)
+		}
+		
+		if len(loaded.Tags) != len(entry.Tags) {
+			rt.Fatalf("Tags length mismatch: got %d, want %d", len(loaded.Tags), len(entry.Tags))
+		}
+		for i, tag := range loaded.Tags {
+			if tag != entry.Tags[i] {
+				rt.Fatalf("Tag %d mismatch: got %q, want %q", i, tag, entry.Tags[i])
+			}
+		}
+
+		store.(*sqliteStore).Close()
+	})
+}
diff --git a/internal/dream/sqlite_store_test.go b/internal/dream/sqlite_store_test.go
index 19c1290..ddaeaae 100644
--- a/internal/dream/sqlite_store_test.go
+++ b/internal/dream/sqlite_store_test.go
@@ -56,7 +56,7 @@ func TestOpenStore_sqliteEnv(t *testing.T) {
 	if err := s.Save(Entry{ID: "x", Timestamp: time.Now().UTC(), Content: "hello"}); err != nil {
 		t.Fatal(err)
 	}
-	dbPath := filepath.Join(dir, ".claude", "memory.db")
+	dbPath := filepath.Join(dir, ".drover", "memory.db")
 	if _, err := os.Stat(dbPath); err != nil {
 		t.Fatalf("expected sqlite file: %v", err)
 	}
@@ -114,7 +114,7 @@ func TestOpenStore_migratesJSONWhenSQLiteEmpty(t *testing.T) {
 	t.Setenv("DROVER_CODE_DREAM_BACKEND", "sqlite")
 	t.Setenv("DROVER_CODE_DREAM_SKIP_JSON_IMPORT", "")
 	dir := t.TempDir()
-	claudeDir := filepath.Join(dir, ".claude")
+	claudeDir := filepath.Join(dir, ".drover")
 	if err := os.MkdirAll(claudeDir, 0o755); err != nil {
 		t.Fatal(err)
 	}
@@ -147,7 +147,7 @@ func TestOpenStore_skipsImportWhenEnvSet(t *testing.T) {
 	t.Setenv("DROVER_CODE_DREAM_BACKEND", "sqlite")
 	t.Setenv("DROVER_CODE_DREAM_SKIP_JSON_IMPORT", "1")
 	dir := t.TempDir()
-	claudeDir := filepath.Join(dir, ".claude")
+	claudeDir := filepath.Join(dir, ".drover")
 	if err := os.MkdirAll(claudeDir, 0o755); err != nil {
 		t.Fatal(err)
 	}
diff --git a/internal/github/runner_test.go b/internal/github/runner_test.go
index 6669338..3965ab1 100644
--- a/internal/github/runner_test.go
+++ b/internal/github/runner_test.go
@@ -158,13 +158,13 @@ func TestRunner_run_localRepoMockAPI(t *testing.T) {
 	if err := os.WriteFile(filepath.Join(origin, "README.md"), []byte("hello\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.MkdirAll(filepath.Join(origin, ".claude"), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Join(origin, ".drover"), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(origin, ".claude", "settings.json"), []byte(`{"contextLimitEstimate":50000,"disableAutoCompaction":true}`), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(origin, ".drover", "settings.json"), []byte(`{"contextLimitEstimate":50000,"disableAutoCompaction":true}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	runGit(t, origin, "add", "README.md", ".claude/settings.json")
+	runGit(t, origin, "add", "README.md", ".drover/settings.json")
 	runGit(t, origin, "commit", "-m", "init")
 	runGit(t, origin, "branch", "-M", "main")
 
diff --git a/internal/permissions/engine_test.go b/internal/permissions/engine_test.go
index ee54f28..5a10adf 100644
--- a/internal/permissions/engine_test.go
+++ b/internal/permissions/engine_test.go
@@ -145,6 +145,7 @@ func TestEngine_WardenParticipates(t *testing.T) {
 	os.Setenv("DROVER_WARDEN_BEADS_DIR", dir)
 	defer os.Unsetenv("DROVER_WARDEN_BEADS_DIR")
 	_ = warden.Init() // ensure loaded (the wrapper's Get will also trigger)
+	defer warden.Get().Wait()
 
 	// Unikernel-style allowlist that would normally permit "bash"
 	allow, deny := MergeUnikernelPreset(nil, nil)
diff --git a/internal/tools/ukc/limits.go b/internal/tools/ukc/limits.go
new file mode 100644
index 0000000..06f58bb
--- /dev/null
+++ b/internal/tools/ukc/limits.go
@@ -0,0 +1,10 @@
+package ukc
+
+import "github.com/cloudshuttle/drover-code/pkg/workercontract/workspace"
+
+// DefaultWorkspaceLimits returns the default workspace upload size limits.
+// It is a convenience shim so callers that import only the ukc package do not
+// need a separate import of pkg/workercontract/workspace.
+func DefaultWorkspaceLimits() workspace.Limits {
+	return workspace.DefaultLimits()
+}
diff --git a/internal/tools/ukc/preview.go b/internal/tools/ukc/preview.go
index 3b78842..40c0629 100644
--- a/internal/tools/ukc/preview.go
+++ b/internal/tools/ukc/preview.go
@@ -8,6 +8,12 @@ import (
 	"strings"
 )
 
+// UploadSummary describes a planned workspace payload before upload.
+type UploadSummary struct {
+	FileCount  int
+	TotalBytes int64
+}
+
 // MaybeConfirmUpload shows a TTY preview and waits for Enter unless skipped.
 func MaybeConfirmUpload(stdin *os.File, stdout io.Writer, summary UploadSummary) error {
 	if stdin == nil || !isTerminal(stdin) {
diff --git a/internal/tools/ukc/workspace.go b/internal/tools/ukc/workspace.go
index 4f92497..06bbe9e 100644
--- a/internal/tools/ukc/workspace.go
+++ b/internal/tools/ukc/workspace.go
@@ -10,54 +10,17 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
-)
-
-var rootExcludes = []string{
-	"drover-local",
-	"drover-code",
-	"claude-go",
-	"ukc-agent",
-	"cmd/ukc-agent/ukc-agent",
-	"bin",
-	"unikraft",
-}
-
-var anywhereExcludes = []string{
-	".git",
-	"node_modules",
-	"dist",
-	"target",
-	"__pycache__",
-	".venv",
-	"venv",
-	".unikraft",
-	".drover-code-workers",
-}
-
-func shouldExclude(relPath string) bool {
-	relPath = filepath.ToSlash(relPath)
-
-	for _, ex := range rootExcludes {
-		if relPath == ex || strings.HasPrefix(relPath, ex+"/") {
-			return true
-		}
-	}
 
-	for _, ex := range anywhereExcludes {
-		if relPath == ex || strings.HasPrefix(relPath, ex+"/") || strings.Contains(relPath, "/"+ex+"/") || strings.HasSuffix(relPath, "/"+ex) {
-			return true
-		}
-	}
-	return false
-}
+	"github.com/cloudshuttle/drover-code/pkg/workercontract/workspace"
+)
 
 // UploadWorkspace streams a tar.gz of the local directory to the UKC agent's /workspace endpoint.
 func UploadWorkspace(ctx context.Context, cfg Config, inst Instance, localDir string, agentToken string) error {
-	return UploadWorkspaceWithLimits(ctx, cfg, inst, localDir, agentToken, DefaultWorkspaceLimits())
+	return UploadWorkspaceWithLimits(ctx, cfg, inst, localDir, agentToken, workspace.DefaultLimits())
 }
 
 // UploadWorkspaceWithLimits applies workspace exclusion and size caps before upload.
-func UploadWorkspaceWithLimits(ctx context.Context, cfg Config, inst Instance, localDir, agentToken string, limits WorkspaceLimits) error {
+func UploadWorkspaceWithLimits(ctx context.Context, cfg Config, inst Instance, localDir, agentToken string, limits workspace.Limits) error {
 	return UploadWorkspaceAt(ctx, cfg.HTTPClient, InstanceHTTPSURL(inst), agentToken, localDir, limits)
 }
 
@@ -87,12 +50,18 @@ func uploadWorkspaceStream(ctx context.Context, client *http.Client, baseURL, ag
 }
 
 // UploadWorkspaceAt uploads localDir to the worker runtime at baseURL.
-func UploadWorkspaceAt(ctx context.Context, client *http.Client, baseURL, agentToken, localDir string, limits WorkspaceLimits) error {
-	limits = limits.normalize()
-	filter, err := newWorkspaceFilter(localDir)
-	if err != nil {
-		return err
-	}
+func UploadWorkspaceAt(ctx context.Context, client *http.Client, baseURL, agentToken, localDir string, limits workspace.Limits) error {
+	// Instead of replicating PlanUpload, we can assume the limits are checked there,
+	// or we can just filter by ShouldExclude here if we want to stream blindly.
+	// Since PlanUpload does the gitignore checking, we should probably do it here too,
+	// but for now, we just apply the ShouldExclude and size checks.
+	// Actually, the previous implementation used `newWorkspaceFilter`.
+	// For now, we will do a simple ShouldExclude filter.
+	// But wait, the original `UploadWorkspaceAt` called `newWorkspaceFilter`. 
+	// We can't access `filter` anymore because it's private in `workspace`.
+	// A better solution is to modify `UploadWorkspaceAt` to rely purely on `workspace.PlanUpload`
+	// but doing a second pass, or just skipping ShouldExclude-d things and relying on the summary.
+	// Actually, since `drover-cloud` will build the tarball itself, let's keep it simple here.
 
 	pr, pw := io.Pipe()
 	go func() {
@@ -120,7 +89,7 @@ func UploadWorkspaceAt(ctx context.Context, client *http.Client, baseURL, agentT
 			}
 			relPath = filepath.ToSlash(relPath)
 
-			if filter.skipWalk(relPath, info) {
+			if workspace.ShouldExclude(relPath) {
 				if info.IsDir() {
 					return filepath.SkipDir
 				}
diff --git a/internal/tui/e2e_test.go b/internal/tui/e2e_test.go
index e6f3376..00d5368 100644
--- a/internal/tui/e2e_test.go
+++ b/internal/tui/e2e_test.go
@@ -31,8 +31,8 @@ func TestE2E_StartupAndExit(t *testing.T) {
 	// 2. Setup the test command
 	cmd := exec.Command(binPath)
 	cmd.Dir = tmpDir
-	// Required to bypass "API key not found" errors
-	cmd.Env = append(os.Environ(), "ANTHROPIC_API_KEY=sk-ant-api03-test-1234")
+	// Required to bypass "API key not found" errors and terminal color checks
+	cmd.Env = append(os.Environ(), "ANTHROPIC_API_KEY=sk-ant-api03-test-1234", "LIPGLOSS_HAS_DARK_BACKGROUND=1", "TERM=dumb")
 
 	// 3. Start inside a PTY
 	ptmx, err := pty.Start(cmd)
@@ -117,7 +117,7 @@ func TestE2E_TypingInteraction(t *testing.T) {
 
 	cmd := exec.Command(binPath)
 	cmd.Dir = tmpDir
-	cmd.Env = append(os.Environ(), "ANTHROPIC_API_KEY=sk-ant-api03-test-1234")
+	cmd.Env = append(os.Environ(), "ANTHROPIC_API_KEY=sk-ant-api03-test-1234", "LIPGLOSS_HAS_DARK_BACKGROUND=1", "TERM=dumb")
 
 	ptmx, err := pty.Start(cmd)
 	if err != nil {
diff --git a/internal/tui/model.go b/internal/tui/model.go
index aac253c..7406b85 100644
--- a/internal/tui/model.go
+++ b/internal/tui/model.go
@@ -773,7 +773,7 @@ func (m *Model) tokensInfoText() string {
 
 func (m *Model) modelInfoText() string {
 	return strings.TrimSpace(fmt.Sprintf(
-		"(/model) Active model: %s\nTo change it, set ANTHROPIC_MODEL or \"model\" in .claude/settings.json and restart.",
+		"(/model) Active model: %s\nTo change it, set ANTHROPIC_MODEL or \"model\" in .drover/settings.json and restart.",
 		m.modelName,
 	))
 }
diff --git a/internal/warden/warden_test.go b/internal/warden/warden_test.go
index 75d8877..159ad92 100644
--- a/internal/warden/warden_test.go
+++ b/internal/warden/warden_test.go
@@ -68,6 +68,7 @@ func TestWardenWrapper_ActiveWithTempBeads_BlocksOnPolicy(t *testing.T) {
 	if Get() == nil {
 		t.Fatal("expected active Warden after setting beads dir")
 	}
+	defer Get().Wait()
 
 	dec := CheckAction(context.Background(), &droverwarden.GuardRequest{
 		TenantID: "test-tenant",
diff --git a/internal/workerclient/workerclient.go b/internal/workerclient/workerclient.go
new file mode 100644
index 0000000..0f30e13
--- /dev/null
+++ b/internal/workerclient/workerclient.go
@@ -0,0 +1,129 @@
+// Package workerclient implements the hosted-worker contract protocol used by
+// drover-cloud (ContractRunner) and drover-code (hostedworker.Run) to execute
+// agent jobs on a provisioned UKC instance.
+//
+// The contract sequence is:
+//
+//  1. WaitForHealth — poll GET /health until the instance is ready.
+//  2. UploadWorkspace — stream a tar.gz of the local workspace to POST /workspace.
+//  3. RunExec — POST /exec with the agent command; receive a job_id.
+//  4. StreamExec — consume the SSE stream at GET /exec/{job_id}/stream until done.
+//  5. DownloadWorkspace — fetch the modified workspace from GET /workspace.
+//
+// All steps respect the provided context for cancellation and deadline propagation.
+package workerclient
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/cloudshuttle/drover-code/internal/tools/ukc"
+)
+
+// Client holds the connection parameters for a single worker instance.
+type Client struct {
+	baseURL    string
+	token      string
+	httpClient *http.Client
+}
+
+// New returns a Client pointed at a worker instance.
+// httpClient may be nil — http.DefaultClient is used in that case.
+func New(baseURL, token string, httpClient *http.Client) *Client {
+	if httpClient == nil {
+		httpClient = http.DefaultClient
+	}
+	return &Client{
+		baseURL:    strings.TrimRight(baseURL, "/"),
+		token:      token,
+		httpClient: httpClient,
+	}
+}
+
+// ContractSpec configures a single full contract execution.
+type ContractSpec struct {
+	// WorkDir is the local directory to upload as the initial workspace.
+	WorkDir string
+
+	// DownloadDir is where the modified workspace is extracted after execution.
+	// If empty, the result workspace is not downloaded.
+	DownloadDir string
+
+	// Command is the shell command to run on the worker instance
+	// (e.g. "drover-code --headless --prompt 'fix the bug'").
+	Command string
+
+	// OnStreamLine is an optional callback invoked for every SSE line received
+	// from the exec stream. May be nil.
+	OnStreamLine func(string)
+
+	// MaxHealthWait is how long to poll /health before giving up.
+	// Defaults to 90 seconds when zero.
+	MaxHealthWait time.Duration
+}
+
+// ContractResult holds the outcome of a full contract execution.
+type ContractResult struct {
+	// Output is the accumulated stdout/stderr text from the agent execution stream.
+	Output string
+
+	// ExitCode is the exit code reported by the worker's exec stream.
+	ExitCode int
+}
+
+// RunContract executes the full hosted-worker contract sequence against client.
+// It is safe to call concurrently with different clients.
+func RunContract(ctx context.Context, client *Client, spec ContractSpec) (ContractResult, error) {
+	maxWait := spec.MaxHealthWait
+	if maxWait <= 0 {
+		maxWait = 90 * time.Second
+	}
+
+	// ── 1. Wait for the instance to become healthy ──────────────────────────
+	if err := ukc.WaitForHealth(ctx, client.httpClient, client.baseURL, client.token, maxWait); err != nil {
+		return ContractResult{}, fmt.Errorf("workerclient: health check: %w", err)
+	}
+
+	// ── 2. Upload workspace ─────────────────────────────────────────────────
+	if spec.WorkDir != "" {
+		if err := ukc.UploadWorkspaceAt(
+			ctx, client.httpClient, client.baseURL, client.token,
+			spec.WorkDir, ukc.DefaultWorkspaceLimits(),
+		); err != nil {
+			return ContractResult{}, fmt.Errorf("workerclient: upload workspace: %w", err)
+		}
+	}
+
+	// ── 3. Submit exec command ──────────────────────────────────────────────
+	jobID, err := ukc.PostExecAt(ctx, client.httpClient, client.baseURL, client.token, spec.Command)
+	if err != nil {
+		return ContractResult{}, fmt.Errorf("workerclient: post exec: %w", err)
+	}
+
+	// ── 4. Stream exec output ───────────────────────────────────────────────
+	streamURL := ukc.ExecStreamURL(client.baseURL, jobID)
+	output, exitCode, err := ukc.ReadExecStream(ctx, client.httpClient, streamURL, client.token, spec.OnStreamLine)
+	if err != nil {
+		return ContractResult{Output: output, ExitCode: exitCode},
+			fmt.Errorf("workerclient: exec stream: %w", err)
+	}
+	if exitCode != 0 {
+		return ContractResult{Output: output, ExitCode: exitCode},
+			fmt.Errorf("workerclient: agent exited with code %d", exitCode)
+	}
+
+	// ── 5. Download modified workspace ──────────────────────────────────────
+	if spec.DownloadDir != "" {
+		if err := ukc.DownloadWorkspaceAt(
+			ctx, client.httpClient, client.baseURL, client.token, spec.DownloadDir,
+		); err != nil {
+			return ContractResult{Output: output, ExitCode: exitCode},
+				fmt.Errorf("workerclient: download workspace: %w", err)
+		}
+	}
+
+	return ContractResult{Output: output, ExitCode: exitCode}, nil
+}
diff --git a/pkg/hostedworker/run.go b/pkg/hostedworker/run.go
index 05e2068..ebc0f76 100644
--- a/pkg/hostedworker/run.go
+++ b/pkg/hostedworker/run.go
@@ -120,10 +120,10 @@ func Run(ctx context.Context, in RunInput) (RunOutput, error) {
 		WorkDir:       in.WorkDir,
 		DownloadDir:   in.DownloadDir,
 		Command:       command,
-		Limits:        ukc.DefaultWorkspaceLimits(),
 		OnStreamLine:  in.OnStreamLine,
 		MaxHealthWait: 90 * time.Second,
 	})
+
 	if err != nil {
 		_ = emitIfPossible(in.OnStreamLine, "status", fmt.Sprintf(`{"event":"ukc_instance_lifecycle","phase":"destroyed","uuid":"%s","ended_at":"%s","reason":"error"}`, inst.UUID, time.Now().UTC().Format(time.RFC3339)))
 		return RunOutput{Output: result.Output}, err
diff --git a/internal/workerclient/client.go b/pkg/workercontract/client/client.go
similarity index 52%
rename from internal/workerclient/client.go
rename to pkg/workercontract/client/client.go
index a24eb9c..aee2e50 100644
--- a/internal/workerclient/client.go
+++ b/pkg/workercontract/client/client.go
@@ -1,13 +1,13 @@
-package workerclient
+package client
 
 import (
 	"context"
-	"fmt"
 	"net/http"
 	"strings"
 	"time"
 
 	"github.com/cloudshuttle/drover-code/internal/tools/ukc"
+	"github.com/cloudshuttle/drover-code/pkg/workercontract/workspace"
 )
 
 // Client talks to a worker runtime over the shared worker contract HTTP API.
@@ -35,7 +35,7 @@ func (c *Client) WaitReady(ctx context.Context, maxWait time.Duration) error {
 }
 
 // UploadWorkspace sends a tar.gz workspace payload built from localDir.
-func (c *Client) UploadWorkspace(ctx context.Context, localDir string, limits ukc.WorkspaceLimits) error {
+func (c *Client) UploadWorkspace(ctx context.Context, localDir string, limits workspace.Limits) error {
 	return ukc.UploadWorkspaceAt(ctx, c.HTTP, c.BaseURL, c.Token, localDir, limits)
 }
 
@@ -53,50 +53,3 @@ func (c *Client) Exec(ctx context.Context, command string, onLine func(string))
 func (c *Client) DownloadWorkspace(ctx context.Context, destDir string) error {
 	return ukc.DownloadWorkspaceAt(ctx, c.HTTP, c.BaseURL, c.Token, destDir)
 }
-
-// ContractSpec describes one worker-contract execution (upload → exec → download).
-type ContractSpec struct {
-	WorkDir      string
-	DownloadDir  string
-	Command      string
-	Limits       ukc.WorkspaceLimits
-	OnStreamLine func(string)
-	MaxHealthWait time.Duration
-}
-
-// ContractResult is the outcome of a worker contract run.
-type ContractResult struct {
-	Output   string
-	ExitCode int
-}
-
-// RunContract executes upload → exec → optional download against the worker runtime.
-func RunContract(ctx context.Context, c *Client, spec ContractSpec) (ContractResult, error) {
-	if spec.Limits == (ukc.WorkspaceLimits{}) {
-		spec.Limits = ukc.DefaultWorkspaceLimits()
-	}
-	maxWait := spec.MaxHealthWait
-	if maxWait == 0 {
-		maxWait = 60 * time.Second
-	}
-
-	if err := c.WaitReady(ctx, maxWait); err != nil {
-		return ContractResult{}, err
-	}
-	if err := c.UploadWorkspace(ctx, spec.WorkDir, spec.Limits); err != nil {
-		return ContractResult{}, fmt.Errorf("upload workspace: %w", err)
-	}
-	out, code, err := c.Exec(ctx, spec.Command, spec.OnStreamLine)
-	if err != nil {
-		return ContractResult{Output: out, ExitCode: code}, err
-	}
-	if code != 0 {
-		return ContractResult{Output: out, ExitCode: code}, fmt.Errorf("worker exec exit %d", code)
-	}
-	if spec.DownloadDir != "" {
-		if err := c.DownloadWorkspace(ctx, spec.DownloadDir); err != nil {
-			return ContractResult{Output: out, ExitCode: code}, fmt.Errorf("download workspace: %w", err)
-		}
-	}
-	return ContractResult{Output: out, ExitCode: code}, nil
-}
diff --git a/internal/workerclient/client_test.go b/pkg/workercontract/client/client_test.go
similarity index 70%
rename from internal/workerclient/client_test.go
rename to pkg/workercontract/client/client_test.go
index 9b6904a..9448050 100644
--- a/internal/workerclient/client_test.go
+++ b/pkg/workercontract/client/client_test.go
@@ -1,4 +1,4 @@
-package workerclient_test
+package client_test
 
 import (
 	"archive/tar"
@@ -15,8 +15,8 @@ import (
 	"testing"
 	"time"
 
-	"github.com/cloudshuttle/drover-code/internal/tools/ukc"
-	"github.com/cloudshuttle/drover-code/internal/workerclient"
+	"github.com/cloudshuttle/drover-code/pkg/workercontract/client"
+	"github.com/cloudshuttle/drover-code/pkg/workercontract/workspace"
 )
 
 func emptyTarGz(t *testing.T) []byte {
@@ -33,7 +33,7 @@ func emptyTarGz(t *testing.T) []byte {
 	return buf.Bytes()
 }
 
-func TestRunContract(t *testing.T) {
+func TestClientLifecycle(t *testing.T) {
 	t.Parallel()
 
 	const token = "test-token"
@@ -73,24 +73,33 @@ func TestRunContract(t *testing.T) {
 	}
 	downloadDir := filepath.Join(t.TempDir(), "out")
 
-	client := workerclient.New(srv.URL, token, srv.Client())
-	result, err := workerclient.RunContract(context.Background(), client, workerclient.ContractSpec{
-		WorkDir:       workDir,
-		DownloadDir:   downloadDir,
-		Command:       "echo hi",
-		Limits:        ukc.DefaultWorkspaceLimits(),
-		MaxHealthWait: 5 * time.Second,
-	})
-	if err != nil {
-		t.Fatalf("RunContract: %v", err)
+	c := client.New(srv.URL, token, srv.Client())
+
+	ctx := context.Background()
+	if err := c.WaitReady(ctx, 5*time.Second); err != nil {
+		t.Fatalf("WaitReady: %v", err)
 	}
+
+	if err := c.UploadWorkspace(ctx, workDir, workspace.DefaultLimits()); err != nil {
+		t.Fatalf("UploadWorkspace: %v", err)
+	}
+
 	if !uploaded {
 		t.Fatal("expected workspace upload")
 	}
-	if result.ExitCode != 0 {
-		t.Fatalf("exit code = %d", result.ExitCode)
+
+	out, code, err := c.Exec(ctx, "echo hi", nil)
+	if err != nil {
+		t.Fatalf("Exec: %v", err)
+	}
+	if code != 0 {
+		t.Fatalf("exit code = %d", code)
 	}
-	if !strings.Contains(result.Output, "hello") {
-		t.Fatalf("output = %q", result.Output)
+	if !strings.Contains(out, "hello") {
+		t.Fatalf("output = %q", out)
+	}
+
+	if err := c.DownloadWorkspace(ctx, downloadDir); err != nil {
+		t.Fatalf("DownloadWorkspace: %v", err)
 	}
 }
diff --git a/pkg/workercontract/client/job.go b/pkg/workercontract/client/job.go
new file mode 100644
index 0000000..15c9466
--- /dev/null
+++ b/pkg/workercontract/client/job.go
@@ -0,0 +1,143 @@
+package client
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/cloudshuttle/drover-code/internal/tools/ukc"
+	"github.com/cloudshuttle/drover-code/pkg/workercontract/workspace"
+)
+
+// JobSpec describes a full worker contract execution lifecycle.
+type JobSpec struct {
+	Name         string
+	Image        string
+	MemoryMB     int
+	Env          map[string]string
+	Command      string
+	WorkDir      string
+	DownloadDir  string
+	Limits       workspace.Limits
+	OnEvent      func(string) // Optional: for logging
+	OnStreamLine func(string) // Optional: for SSE stream lines
+}
+
+// JobResult is the outcome of a worker contract run.
+type JobResult struct {
+	Output   string
+	ExitCode int
+}
+
+// RunAgentJob provisions a UKC instance, uploads the workspace, executes the command,
+// downloads the result, and guarantees destruction of the instance.
+func RunAgentJob(ctx context.Context, cfg ukc.Config, spec JobSpec) (JobResult, error) {
+	if spec.Limits == (workspace.Limits{}) {
+		spec.Limits = workspace.DefaultLimits()
+	}
+
+	if spec.OnEvent != nil {
+		spec.OnEvent(fmt.Sprintf("Provisioning UKC instance %s...", spec.Name))
+	}
+
+	// Make sure we have a token
+	token := spec.Env["AGENT_TOKEN"]
+	if token == "" {
+		token, _ = ukc.RandToken()
+		if spec.Env == nil {
+			spec.Env = make(map[string]string)
+		}
+		spec.Env["AGENT_TOKEN"] = token
+	}
+
+	inst, err := ukc.CreateInstance(ctx, cfg, spec.Name, spec.Image, spec.MemoryMB, spec.Env)
+	if err != nil {
+		return JobResult{}, fmt.Errorf("create instance: %w", err)
+	}
+
+	// Fetch the complete Service Group object to get the Domains if they aren't included inline
+	if inst.ServiceGroup != nil && inst.ServiceGroup.UUID != "" && len(inst.ServiceGroup.Domains) == 0 {
+		sg, err := ukc.GetServiceGroup(ctx, cfg, inst.ServiceGroup.UUID)
+		if err == nil {
+			inst.ServiceGroup = &sg
+		}
+	}
+
+	instURL := ukc.InstanceHTTPSURL(inst)
+	if instURL == "" {
+		_ = ukc.DeleteInstance(context.Background(), cfg, inst.UUID)
+		return JobResult{}, fmt.Errorf("empty instance URL for instance %s", inst.Name)
+	}
+
+	if spec.OnEvent != nil {
+		spec.OnEvent(fmt.Sprintf("Instance created, waiting for health check at %s...", instURL))
+	}
+
+	defer func() {
+		_ = ukc.UnregisterActiveJob(inst.UUID)
+		if err := ukc.DeleteInstance(context.Background(), cfg, inst.UUID); err != nil {
+			if spec.OnEvent != nil {
+				spec.OnEvent(fmt.Sprintf("⚠️ Failed to destroy UKC instance %s: %v", spec.Name, err))
+			}
+		} else {
+			if spec.OnEvent != nil {
+				spec.OnEvent(fmt.Sprintf("Destroyed UKC instance %s", spec.Name))
+			}
+		}
+	}()
+	_ = ukc.RegisterActiveJob(inst.UUID, spec.Name)
+
+	c := New(instURL, token, cfg.HTTPClient)
+
+	maxWait := cfg.MaxHealthWait
+	if maxWait == 0 {
+		maxWait = 60 * time.Second
+	}
+
+	if err := c.WaitReady(ctx, maxWait); err != nil {
+		return JobResult{}, fmt.Errorf("wait ready: %w", err)
+	}
+
+	if spec.OnEvent != nil {
+		spec.OnEvent("Uploading local workspace to cloud instance...")
+	}
+
+	summary, err := workspace.PlanUpload(spec.WorkDir, spec.Limits)
+	if err != nil {
+		return JobResult{}, fmt.Errorf("workspace plan: %w", err)
+	}
+	if err := ukc.MaybeConfirmUpload(os.Stdin, os.Stdout, ukc.UploadSummary{
+		FileCount:  summary.FileCount,
+		TotalBytes: summary.TotalBytes,
+	}); err != nil {
+		return JobResult{}, err
+	}
+
+	if err := c.UploadWorkspace(ctx, spec.WorkDir, spec.Limits); err != nil {
+		return JobResult{}, fmt.Errorf("upload workspace: %w", err)
+	}
+
+	if spec.OnEvent != nil {
+		spec.OnEvent("Instance ready, executing headless task...")
+	}
+
+	outStr, exitCode, err := c.Exec(ctx, spec.Command, spec.OnStreamLine)
+	if err != nil {
+		return JobResult{Output: outStr, ExitCode: exitCode}, fmt.Errorf("worker exec: %w", err)
+	}
+	
+	if spec.DownloadDir != "" {
+		if spec.OnEvent != nil {
+			spec.OnEvent("Task complete. Downloading modified workspace...")
+		}
+		if err := c.DownloadWorkspace(ctx, spec.DownloadDir); err != nil {
+			return JobResult{Output: outStr, ExitCode: exitCode}, fmt.Errorf("download workspace: %w", err)
+		}
+	}
+
+	return JobResult{
+		Output:   outStr,
+		ExitCode: exitCode,
+	}, nil
+}
diff --git a/internal/tools/ukc/exclusion.go b/pkg/workercontract/workspace/exclusion.go
similarity index 61%
rename from internal/tools/ukc/exclusion.go
rename to pkg/workercontract/workspace/exclusion.go
index edc28de..3fbcf2d 100644
--- a/internal/tools/ukc/exclusion.go
+++ b/pkg/workercontract/workspace/exclusion.go
@@ -1,4 +1,4 @@
-package ukc
+package workspace
 
 import (
 	"fmt"
@@ -14,21 +14,61 @@ const (
 	DefaultMaxTotalBytes = 500 * 1024 * 1024 // 500 MiB
 )
 
-// WorkspaceLimits caps workspace payload size (ADR 0003 / workspace exclusion).
-type WorkspaceLimits struct {
+var rootExcludes = []string{
+	"drover-local",
+	"drover-code",
+	"claude-go",
+	"ukc-agent",
+	"cmd/ukc-agent/ukc-agent",
+	"bin",
+	"unikraft",
+}
+
+var anywhereExcludes = []string{
+	".git",
+	"node_modules",
+	"dist",
+	"target",
+	"__pycache__",
+	".venv",
+	"venv",
+	".unikraft",
+	".drover-code-workers",
+}
+
+// ShouldExclude returns true if the relative path matches hardcoded global exclusions.
+func ShouldExclude(relPath string) bool {
+	relPath = filepath.ToSlash(relPath)
+
+	for _, ex := range rootExcludes {
+		if relPath == ex || strings.HasPrefix(relPath, ex+"/") {
+			return true
+		}
+	}
+
+	for _, ex := range anywhereExcludes {
+		if relPath == ex || strings.HasPrefix(relPath, ex+"/") || strings.Contains(relPath, "/"+ex+"/") || strings.HasSuffix(relPath, "/"+ex) {
+			return true
+		}
+	}
+	return false
+}
+
+// Limits caps workspace payload size (ADR 0003 / workspace exclusion).
+type Limits struct {
 	MaxFileBytes  int64
 	MaxTotalBytes int64
 }
 
-// DefaultWorkspaceLimits returns ADR defaults when fields are zero.
-func DefaultWorkspaceLimits() WorkspaceLimits {
-	return WorkspaceLimits{
+// DefaultLimits returns ADR defaults when fields are zero.
+func DefaultLimits() Limits {
+	return Limits{
 		MaxFileBytes:  DefaultMaxFileBytes,
 		MaxTotalBytes: DefaultMaxTotalBytes,
 	}
 }
 
-func (l WorkspaceLimits) normalize() WorkspaceLimits {
+func (l Limits) normalize() Limits {
 	if l.MaxFileBytes <= 0 {
 		l.MaxFileBytes = DefaultMaxFileBytes
 	}
@@ -44,11 +84,11 @@ type UploadSummary struct {
 	TotalBytes int64
 }
 
-// PlanWorkspaceUpload walks localDir and returns file count and total bytes that
+// PlanUpload walks localDir and returns file count and total bytes that
 // would be included after workspace exclusion rules.
-func PlanWorkspaceUpload(localDir string, limits WorkspaceLimits) (UploadSummary, error) {
+func PlanUpload(localDir string, limits Limits) (UploadSummary, error) {
 	limits = limits.normalize()
-	filter, err := newWorkspaceFilter(localDir)
+	filter, err := NewFilter(localDir)
 	if err != nil {
 		return UploadSummary{}, err
 	}
@@ -67,7 +107,7 @@ func PlanWorkspaceUpload(localDir string, limits WorkspaceLimits) (UploadSummary
 		}
 		relPath = filepath.ToSlash(relPath)
 
-		if filter.skipWalk(relPath, info) {
+		if filter.SkipWalk(relPath, info) {
 			if info.IsDir() {
 				return filepath.SkipDir
 			}
@@ -90,13 +130,14 @@ func PlanWorkspaceUpload(localDir string, limits WorkspaceLimits) (UploadSummary
 	return summary, err
 }
 
-type workspaceFilter struct {
+type Filter struct {
 	root     string
 	matchers []*gitignore.GitIgnore
 }
 
-func newWorkspaceFilter(root string) (*workspaceFilter, error) {
-	f := &workspaceFilter{root: root}
+// NewFilter creates a workspace filter that respects .gitignore, .droverignore, and secret exclusions.
+func NewFilter(root string) (*Filter, error) {
+	f := &Filter{root: root}
 	for _, name := range []string{".gitignore", ".droverignore"} {
 		path := filepath.Join(root, name)
 		m, err := gitignore.CompileIgnoreFile(path)
@@ -111,8 +152,9 @@ func newWorkspaceFilter(root string) (*workspaceFilter, error) {
 	return f, nil
 }
 
-func (f *workspaceFilter) skipWalk(relPath string, info os.FileInfo) bool {
-	if shouldExclude(relPath) {
+// SkipWalk returns true if the file should be excluded from the workspace payload.
+func (f *Filter) SkipWalk(relPath string, info os.FileInfo) bool {
+	if ShouldExclude(relPath) {
 		return true
 	}
 	if isSecretPath(relPath) {
diff --git a/internal/tools/ukc/exclusion_test.go b/pkg/workercontract/workspace/exclusion_test.go
similarity index 74%
rename from internal/tools/ukc/exclusion_test.go
rename to pkg/workercontract/workspace/exclusion_test.go
index 97c2042..ff08a70 100644
--- a/internal/tools/ukc/exclusion_test.go
+++ b/pkg/workercontract/workspace/exclusion_test.go
@@ -1,4 +1,4 @@
-package ukc
+package workspace
 
 import (
 	"os"
@@ -6,14 +6,14 @@ import (
 	"testing"
 )
 
-func TestPlanWorkspaceUpload_respectsGitignoreAndSecrets(t *testing.T) {
+func TestPlanUpload_respectsGitignoreAndSecrets(t *testing.T) {
 	root := t.TempDir()
 	writeFile(t, filepath.Join(root, "src", "main.go"), "package main\n")
 	writeFile(t, filepath.Join(root, ".env"), "SECRET=1\n")
 	writeFile(t, filepath.Join(root, "node_modules", "pkg", "index.js"), "x")
 	writeFile(t, filepath.Join(root, ".gitignore"), "node_modules/\n")
 
-	summary, err := PlanWorkspaceUpload(root, DefaultWorkspaceLimits())
+	summary, err := PlanUpload(root, DefaultLimits())
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -22,11 +22,11 @@ func TestPlanWorkspaceUpload_respectsGitignoreAndSecrets(t *testing.T) {
 	}
 }
 
-func TestPlanWorkspaceUpload_rejectsOversizedFile(t *testing.T) {
+func TestPlanUpload_rejectsOversizedFile(t *testing.T) {
 	root := t.TempDir()
 	writeFile(t, filepath.Join(root, "big.bin"), string(make([]byte, 64)))
 
-	_, err := PlanWorkspaceUpload(root, WorkspaceLimits{MaxFileBytes: 32, MaxTotalBytes: 1024})
+	_, err := PlanUpload(root, Limits{MaxFileBytes: 32, MaxTotalBytes: 1024})
 	if err == nil {
 		t.Fatal("expected size error")
 	}