Submatter/plans/Plan-automation-foundation/Epic-apps-worker-v1/Epic-apps-worker-v1.md

---
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-12"
---

# 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`).

## Status note (2026-08-12)

- Tool loop + checkpoints are **implemented in code**; task files marked done.
- **Gap:** worker does **not** yet open draft PRs via forge adapter (blocks clean Epic 8 dogfood).
- **A1 live E2E** (Go → unattended job on real Redis/Coolify) needs explicit operator verify: [Task-worker-live-e2e-dogfood](./Task-worker-live-e2e-dogfood.md).

## 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).
- Live deploy dogfood checklist.

**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) until draft PR task lands.

## Acceptance criteria

- [ ] One brief from `.convoys/` completes unattended on connected repo (see live E2E task).
- [x] Checkpoint resume after kill (code + task done).
- [ ] Draft PR opened on implementer success.
- [ ] `complete_task` includes model alias + token totals on live run.

## Tasks

| Task | Link | Status |
|------|------|--------|
| Minimal tool loop + worktree | [Task-worker-minimal-tool-loop](./Task-worker-minimal-tool-loop.md) | done (code; confirm live via E2E task) |
| Checkpoint & crash recovery | [Task-worker-checkpoint-resume](./Task-worker-checkpoint-resume.md) | done |
| Draft PR via forge | [Task-worker-draft-pr](./Task-worker-draft-pr.md) | **ready** |
| Live E2E dogfood (A1 verify) | [Task-worker-live-e2e-dogfood](./Task-worker-live-e2e-dogfood.md) | **ready** |
| Operator notes mid-build | [Task-worker-operator-notes](./Task-worker-operator-notes.md) | draft |