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

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

Worker coordination service contract

Implement cross-repository worker wake-up and dependency coordination requested by net-kingdom. Coordination-engine owns observation, policy, coordination leases, checkpoints and receipts. State Hub and standalone tmux-amq are adapters. Only explicitly selected, gita-registered repos are valid worker targets.

2026-09-07: finished. The operator approved the documented deployment defaults and transfer of canon review/registration to COORDINATION-WP-0004. Implementation and local verification are complete. The service has not been enabled or used to inject a live worker wake.

Publish the v0.1 contract

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. Reconciled on 2026-09-07 with TAMQ's implemented adapter and the local-alpha runtime. The original speculative proposal is preserved under history/260907-worker-coordination-service-v0.1-proposal.md. The separate coordination-engine executable avoids replacing TAMQ's own tamq CLI. TAMQ owns endpoint registration, transport profiles, queue/history/export/ replay, session lifecycle and unsafe local diagnostics. See ADR-002.

Agree adapter and deployment decisions

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

Implemented boundary: consume the published TAMQ v0.1 socket protocol, negotiate required capabilities, preserve endpoint/message identity, refresh gita and require exact configured targets. TAMQ remains responsible for slug/path registration and local delivery. Coordination-engine does not introduce a second inbound TAMQ attach handshake.

Approved deployment defaults are in docs/worker-runtime.md and docs/adr/002-worker-runtime-boundary.md: same approved Unix user, mode-0600 sockets, explicit TAMQ socket, private XDG coordination state, retained history, SQLite snapshots before migrations, 15-second polling, 30-second lease, 10-second renewal, four attempts, 5/15/60/300-second delays, zero safety retries, and a conservative default policy. Repository selection is mandatory and empty by default. No credentials are stored in configuration.

2026-09-07: operator explicitly approved these defaults in response to the closure request. This records configuration decisions; live service activation remains a separate operational action requiring selected repository targets.

Establish OrwellLoggingDiagnostics practice pattern

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

Prepared docs/orwell-logging-diagnostics-candidate.md for practice-pattern/orwell-logging-diagnostics, with TAMQ as the known consumer. Coordination-engine emits sanitized receipts and has no unsafe logging mode.

No matching canonical artifact was found in the current info-tech-canon checkout. Its infospace/assimilation/intake-and-assimilation-practice.md requires explicit owner disposition before registration. Owner review/registration remains pending. 2026-09-07: operator explicitly approved moving canon review/registration to workplans/COORDINATION-WP-0004-orwell-canon-review.md. T04 closes with the prepared candidate and approved scope transfer; canonical acceptance is not claimed. The follow-up preserves owner disposition and registration criteria.

Implement the coordination runtime

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

Implemented Python 3.11+ standard-library runtime with uv packaging and a coordination-engine entry point. Includes:

• State Hub observation, task/workplan dependencies, explicit actionable inbox markers, complete-snapshot gating and outage backoff.
• Same-user TAMQ socket client, version/capability negotiation, exact endpoint selection, fresh gita validation and idempotent admission.
• Transactional SQLite leases/receipts, per-repo exclusion, bounded retries, restart recovery, schema guard, snapshots and private local storage.
• Worker ack/renew/checkpoint/complete control socket; checkpoint continuation receives a new linked trigger while transport recovery preserves lease identity.
• Conservative safety stops, sanitized durable projection outbox, safe diagnostics, CLI help/version/completion, foreground lifecycle and a deployment/recovery runbook.

Validation on 2026-09-07: make check passes (54 tests passed, one opt-in live smoke skipped; diff whitespace, compileall and help/version pass). uv build produces wheel and source distribution. Tests use fake HTTP/gita/TAMQ peers, actual temporary Unix sockets and foreground service stop/restart. No production credentials, live worker injection, or deployment were required. The synchronous local-alpha observer's small-worker-set limitation is documented in the runbook.