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: finished
owner: codex
topic_slug: communication
created: "2026-08-23"
updated: "2026-09-07"
state_hub_workstream_id: "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

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

```task
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

```task
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

```task
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.