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

id	type	title	domain	repo	status	owner	topic_slug	created	updated
COORDINATION-WP-0003	workplan	Worker coordination service contract	communication	coordination-engine	ready	codex	communication	2026-08-23	2026-08-23

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

id: COORDINATION-WP-0003-T01
status: done
priority: high

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

id: COORDINATION-WP-0003-T02
status: wait
priority: high

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

id: COORDINATION-WP-0003-T04
status: wait
priority: medium

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

id: COORDINATION-WP-0003-T03
status: wait
priority: high

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.