Submatter/plans/Plan-automation-foundation/Epic-apps-worker-v1/Task-worker-minimal-tool-loop.md

---
kind: task
slug: worker-minimal-tool-loop
title: apps/worker — minimal tool loop and worktree-per-brief
plan_slug: automation-foundation
epic_slug: apps-worker-v1
status: done
priority: P1
tenant_id: global
owner: unassigned
cursor_todo_id: null
updated_at: "2026-08-12"
agent_prompt: |-
  Epic: apps/worker v1. Read docs/worker.md and docs/adr-model-routing.md.
  Consume orchestrator jobs from Redis; resolve model via workspace registry.
  claim_task / complete_task parity with MCP. Run pnpm lint && pnpm type-check
  && pnpm test before done.
---

# Task summary

Ship the baseline `apps/worker` consumer: dequeue `role_dispatch` jobs, run `WorkerSession` tool loop against a git worktree, and close with model + token metadata on `complete_task`.

## Description

Core v1 scope from [Epic-apps-worker-v1](./Epic-apps-worker-v1.md). Builds on existing package skeleton (`handle-job.ts`, `minimal-session.ts`, allowlisted tools, worktree helpers).

### Worker loop

- `BLPOP` on `echodo:orchestrator:jobs` (same key as orchestrator).
- Load brief path + role from job payload; resolve model via shared resolver.
- `claim_task` on matching backlog item; run `read_file` / `write_file` / `grep` / `run_command` (allowlist: `pnpm lint`, `pnpm type-check`, `pnpm test`, `git status`, `git diff`).
- `complete_task` with `modelAlias`, token totals, outcome.

### Git

- One worktree per brief under `WORKER_WORKTREE_BASE`.
- Branch naming convention documented for Epic 8 PR linking.

### PR output

- Open draft PR via forge adapter from connected repo (Epic 3).

## Subtasks

- [ ] Wire live dequeue loop (non-dry-run) end-to-end
- [ ] Role prompt = `.cursor/agents/role-*.md` + brief markdown path
- [ ] Worktree create/teardown on success and failure
- [ ] Draft PR via forge adapter when implementer completes
- [ ] `docs/worker.md` matches shipped behavior

## Estimation

L

## Acceptance criteria

- [ ] One implementer brief from `.convoys/` completes unattended on a connected repo
- [ ] `complete_task` includes model alias + token totals
- [ ] Failed runs tear down worktree and mark run `failed`
- [ ] `WORKER_DRY_RUN=1` still exits cleanly without Redis

## Links

- Epic: `./Epic-apps-worker-v1.md`
- Plan: `../Plan-automation-foundation.md`
- Design reference: Autensa convoy build phase (concepts only — no OpenClaw dependency)
docs(plans): add Autensa benchmark tasks to automation foundation roadmap Map reliability, operator UX, and spend-control follow-ons onto epics 1–9 so worker, webhooks, and fleet work have bead-scale task briefs. Co-authored-by: Cursor <cursoragent@cursor.com> 2026-08-03 11:48:36 -04:00			`---`
			`kind: task`
			`slug: worker-minimal-tool-loop`
			`title: apps/worker — minimal tool loop and worktree-per-brief`
			`plan_slug: automation-foundation`
			`epic_slug: apps-worker-v1`
feat(second-brain): open self-hosted Obsidian for crews — harness-agnostic v0.1 - MCP create-backlog-item for natural language Plan/Epic/Task authoring - Worker non-code: optional worktree + per-harness allowlist + doc_review→published - Harness registry: harness_providers/role_harness_routes, WorkerAdapter (minimal\|crewai\|langgraph\|remote-ag-ui), AG-UI POST /api/ag-ui, Settings → Harnesses with Test - Plans tree: backlog.listTree + createPlan/Epic/Task + Start→Convoy, web CRUD without CLI - Fleet: /fleet rollup across workspaces + SSE /api/fleet/events Decision: docs/decisions/2026-08-25-second-brain-os-pivot.md Convoy: .convoys/second-brain-os-v01 Co-authored-by: orchestrator 2026-08-25 17:20:53 -04:00			`status: done`
docs(plans): add Autensa benchmark tasks to automation foundation roadmap Map reliability, operator UX, and spend-control follow-ons onto epics 1–9 so worker, webhooks, and fleet work have bead-scale task briefs. Co-authored-by: Cursor <cursoragent@cursor.com> 2026-08-03 11:48:36 -04:00			`priority: P1`
			`tenant_id: global`
			`owner: unassigned`
			`cursor_todo_id: null`
feat(second-brain): open self-hosted Obsidian for crews — harness-agnostic v0.1 - MCP create-backlog-item for natural language Plan/Epic/Task authoring - Worker non-code: optional worktree + per-harness allowlist + doc_review→published - Harness registry: harness_providers/role_harness_routes, WorkerAdapter (minimal\|crewai\|langgraph\|remote-ag-ui), AG-UI POST /api/ag-ui, Settings → Harnesses with Test - Plans tree: backlog.listTree + createPlan/Epic/Task + Start→Convoy, web CRUD without CLI - Fleet: /fleet rollup across workspaces + SSE /api/fleet/events Decision: docs/decisions/2026-08-25-second-brain-os-pivot.md Convoy: .convoys/second-brain-os-v01 Co-authored-by: orchestrator 2026-08-25 17:20:53 -04:00			`updated_at: "2026-08-12"`
			`agent_prompt: \|-`
docs(plans): add Autensa benchmark tasks to automation foundation roadmap Map reliability, operator UX, and spend-control follow-ons onto epics 1–9 so worker, webhooks, and fleet work have bead-scale task briefs. Co-authored-by: Cursor <cursoragent@cursor.com> 2026-08-03 11:48:36 -04:00			`Epic: apps/worker v1. Read docs/worker.md and docs/adr-model-routing.md.`
			`Consume orchestrator jobs from Redis; resolve model via workspace registry.`
			`claim_task / complete_task parity with MCP. Run pnpm lint && pnpm type-check`
			`&& pnpm test before done.`
			`---`

			`# Task summary`

			Ship the baseline `apps/worker` consumer: dequeue `role_dispatch` jobs, run `WorkerSession` tool loop against a git worktree, and close with model + token metadata on `complete_task`.

			`## Description`

			Core v1 scope from [Epic-apps-worker-v1](./Epic-apps-worker-v1.md). Builds on existing package skeleton (`handle-job.ts`, `minimal-session.ts`, allowlisted tools, worktree helpers).

			`### Worker loop`

			- `BLPOP` on `echodo:orchestrator:jobs` (same key as orchestrator).
			`- Load brief path + role from job payload; resolve model via shared resolver.`
			- `claim_task` on matching backlog item; run `read_file` / `write_file` / `grep` / `run_command` (allowlist: `pnpm lint`, `pnpm type-check`, `pnpm test`, `git status`, `git diff`).
			- `complete_task` with `modelAlias`, token totals, outcome.

			`### Git`

			- One worktree per brief under `WORKER_WORKTREE_BASE`.
			`- Branch naming convention documented for Epic 8 PR linking.`

			`### PR output`

			`- Open draft PR via forge adapter from connected repo (Epic 3).`

			`## Subtasks`

			`- [ ] Wire live dequeue loop (non-dry-run) end-to-end`
			- [ ] Role prompt = `.cursor/agents/role-*.md` + brief markdown path
			`- [ ] Worktree create/teardown on success and failure`
			`- [ ] Draft PR via forge adapter when implementer completes`
			- [ ] `docs/worker.md` matches shipped behavior

			`## Estimation`

			`L`

			`## Acceptance criteria`

			- [ ] One implementer brief from `.convoys/` completes unattended on a connected repo
			- [ ] `complete_task` includes model alias + token totals
			- [ ] Failed runs tear down worktree and mark run `failed`
			- [ ] `WORKER_DRY_RUN=1` still exits cleanly without Redis

			`## Links`

			- Epic: `./Epic-apps-worker-v1.md`
			- Plan: `../Plan-automation-foundation.md`
			`- Design reference: Autensa convoy build phase (concepts only — no OpenClaw dependency)`