---
kind: epic
slug: apps-worker-v1
title: apps/worker v1 — minimal Echodo coding agent
plan_slug: automation-foundation
status: in_progress
priority: P1
tenant_id: global
cursor_epic_id: null
updated_at: "2026-08-03"
---

# Epic objective

First-party **`apps/worker`**: minimal agent runtime in the Echodo monorepo (not OpenHands). Docker sandbox per job, tool loop (`read_file`, `write_file`, `grep`, `run_command` with allowlist), git worktree per brief, MCP `claim_task` / `complete_task`, inference via `ResolvedModel` from orchestrator.

Role prompt = `.cursor/agents/role-*.md` + brief path. Model endpoint points at operator Mac (**Ollama or MLX server** — see ADR § Local MLX) or cloud APIs per registry.

**Parallel implementers:** When orchestrator dispatches N implementers to the same Mac inference host, prefer a batching-capable MLX server (**mlx-openai-server**) over `mlx_lm.server` alone. Document chosen server + port in workspace provider alias (`qwen-coder-mlx`).

## In scope / out of scope

**In scope**

- `WorkerSession` adapter interface (for future optional OpenHands plug-in).
- `pnpm lint && pnpm test` in allowlisted commands.
- Branch + PR draft output (forge adapter from Epic 3).
- Checkpoint/resume and operator mid-build notes (Autensa benchmark — see tasks below).

**Out of scope**

- Browser automation, multi-agent delegation.
- Feature parity with OpenHands.
- OpenClaw Gateway coupling.

## Dependencies

- Epic 1, 3, 6.

## Blocks

- Epic 8 (meaningful PR webhook dogfood).

## Acceptance criteria

- [ ] One brief from `.convoys/` completes unattended on connected repo.
- [ ] `complete_task` includes model alias + token totals.
- [ ] Crashed worker can resume from checkpoint (follow-on task).

## Tasks

| Task | Link | Status |
|------|------|--------|
| Minimal tool loop + worktree | [Task-worker-minimal-tool-loop](./Task-worker-minimal-tool-loop.md) | ready |
| Checkpoint & crash recovery | [Task-worker-checkpoint-resume](./Task-worker-checkpoint-resume.md) | draft |
| Operator notes mid-build | [Task-worker-operator-notes](./Task-worker-operator-notes.md) | draft |