coordination-engine/workplans/COORDINATION-WP-0003-worker-coordination-service.md

---
id: COORDINATION-WP-0003
type: workplan
title: "Worker coordination service contract"
domain: communication
repo: coordination-engine
status: ready
owner: codex
topic_slug: communication
created: "2026-08-23"
updated: "2026-08-23"
state_hub_workstream_id: "78a91239-ae31-5e03-98c9-54f3cbe90cb5"
---

# Worker coordination service contract

Define and implement the cross-repository worker wake-up and
dependency-coordination capability requested by net-kingdom. Coordination-engine
owns the protocol and runtime. State Hub and the separate `tmux-amq` local tmux
message queue are adapters. Only gita-registered repos are valid worker targets.

## Publish the v0.1 contract

```task
id: COORDINATION-WP-0003-T01
status: done
priority: high
state_hub_task_id: "a9e407aa-ac92-50b2-8aed-afb74e17e84f"
```

Authored `spec/worker-coordination-service-v0.1.md`, covering State Hub
observation, actionability gates, leases, deduplication, wake requests,
checkpoints, retries, safety stops, receipts, and operator decisions.

## Agree adapter and deployment decisions

```task
id: COORDINATION-WP-0003-T02
status: wait
priority: high
state_hub_task_id: "1a428ed2-01d4-5af7-9341-db83712da9d9"
```

The local transport is a Unix domain socket. Coordination-engine uses local
SQLite for coordination leases, deduplication, and receipts, projecting
sanitized state to State Hub. Net-kingdom/operator must choose the socket
path (same-user mode `0600` by default), `tmux-amq` handshake fields, SQLite
retention/backup policy, timers/retry defaults, the configured policy profile,
and strict gita registry validation. Policy profiles define the allowed and
human-gated action classes. v0.1 uses direct-only routing; broadcast is deferred.
Delivery acknowledgment is configurable and defaults to `injected`; this layer
does not duplicate State Hub task/workplan state.
Message bodies are UTF-8 plain text with an 8 KiB limit and structured metadata
kept in the transport envelope.
Endpoint identity is `tmux-amq-<tmux-server-PID>`; each endpoint has at most one
tmux window per gita repository.
tmux-amq must support local history inspection, export to a messages file, and
safe replay of that file through normal routing and policy checks.
History is retained by default; explicit `tamq purge` uses `--before 365d` and
`--max-size 100MB` defaults, with a startup advisory when history exceeds 100MB.
The service uses `tamq start`/`serve`/`stop`; first repo opening auto-starts an
absent service with an idempotent lock-protected check.
Logging defaults to safe stderr/file output; `--orwell` is an explicit,
non-production, local-only mode for otherwise-omitted sensitive diagnostics.

## Establish OrwellLoggingDiagnostics practice pattern

```task
id: COORDINATION-WP-0003-T04
status: wait
priority: medium
state_hub_task_id: "4ba98e37-cd98-5fb6-9065-4d241dfbabd2"
```

Requested candidate canon artifact `practice-pattern/orwell-logging-diagnostics`
from info-tech-canon, with tamq as the first known use. Await canonical owner
review and registration.

The first runtime implementation is Python 3.11+ with standard-library-first
dependencies.
Package through root `pyproject.toml` with a `tamq` console entry point and uv
install/editable-install support.
Verification uses pytest unit, fake-peer integration, CLI, and opt-in live
smoke tests without production credentials.
Default CI gates: `uv run pytest`, `git diff --check`, compileall, and tamq
help/version checks; package and live smoke checks remain opt-in.
The executable name is `tamq`, with Unix-standard `--help`/`-h` and
`--version`/`-V` flags.
Use XDG config/state/runtime paths with environment overrides and provide
`tamq completion bash|zsh|fish` for tab expansion.
`tmux-amq` independently owns its durable queue and local delivery leases.
Lease/retry timing and attempt counts are configuration parameters; the retry
ceiling is 9, while safety-gated retries default to 0 and require explicit
policy. Runtime ownership is coordination-engine;
tmux/session ownership is `tmux-amq`.

## Implement the coordination runtime

```task
id: COORDINATION-WP-0003-T03
status: wait
priority: high
state_hub_task_id: "074e42ed-2049-5379-aac8-bb3b88672f60"
```

Deferred while `tmux-amq` is bootstrapped as the standalone local queue and
tmux control-mode endpoint. Coordination-engine integration will follow the
stable tamq Unix-socket protocol.