docs: align TAMQ worker adapter contract

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc

README.md

@@ -1 +1,32 @@
-Framework for digital coordination as goal-driven communication .
+# Coordination Engine
+
+Framework for digital coordination as goal-driven communication.
+
+## TAMQ worker-session adapter
+
+Coordination-engine owns trigger observation, actionability and safety policy,
+coordination leases, checkpoints, and State Hub receipts. TAMQ separately owns
+local repository sessions, durable messages, terminal delivery attempts, and
+acknowledgement state.
+
+The implemented async boundary is provided by `tamq.client`:
+
+```python
+from tamq.client import CoordinationEngineAdapter, WakeRequest
+
+receipt = await CoordinationEngineAdapter().wake(
+    WakeRequest(
+        lease_id="lease-123",
+        trigger_id="task-456:r7",
+        target_repo="audit-core",
+        prompt="Resume the actionable task and publish a checkpoint.",
+    )
+)
+```
+
+The coordination lease ID makes wake admission idempotent. An exact live TAMQ
+endpoint is required; the adapter will not choose between multiple sessions or
+start an agent implicitly. Transport states (`pending`, `awaiting_ack`,
+`injected`, `acknowledged`, `failed`) are receipts, not workflow completion.
+See `spec/worker-coordination-service-v0.1.md` and the canonical
+`tmux-amq/spec/coordination-engine-adapter-v0.1.md` contract.

spec/worker-coordination-service-v0.1.md

@@ -113,33 +113,33 @@ produces a stopped receipt for operator review.
 ## 5. Session wake contract
 
 The runtime integrates with `tmux-amq`, a separate local repository that owns
-tmux session lifecycle, durable queueing, local leases, and PTY injection.
+tmux session lifecycle, durable queueing, delivery leases, acknowledgement
-`tmux-amq` MUST remain functional when coordination-engine is unavailable.
+state, and PTY interaction. `tmux-amq` remains functional when
+coordination-engine is unavailable. The implemented transport contract is
+`tmux-amq/spec/coordination-engine-adapter-v0.1.md`; this section summarizes its
+coordination-engine-facing obligations.
+
 Only repositories registered in gita may be addressed. A session may be started
-with, for example,
+with, for example, `tamq --command codex --mode trigger net-kingdom
-`tamq --cmd "codex" net-kingdom railiance-platform`; the bridge opens one
+railiance-platform`; TAMQ opens one terminal per repository and runs the command
-terminal per repository and runs the command. Messages addressed as
+only because the operator selected it explicitly. Operator or worker messages
-`@repo: text` are queued/injected into that repository's terminal as
+use `To:repo: text` and arrive in non-routable `From:sender[/o]: text`
-`#sender-repo: text`. Coordination-engine calls the bridge through a local,
+envelopes. Coordination-engine calls TAMQ through the same-user Unix-socket
-authenticated adapter; it does not manipulate tmux directly.
+adapter and never manipulates tmux directly.
 
 Each tmux-amq endpoint is identified as `tmux-amq-<PID>`, where `<PID>` is the
 tmux server PID. Within one endpoint, a repository slug maps to exactly one
 tmux window; duplicate windows for the same repo are rejected or reconciled
 before attach. Different endpoint PIDs may independently host the same repo.
 
-Outbound messages typed directly by an agent are detected through a tamq
+Outbound messages are observed by TAMQ's explicit PTY broker. A worker
-tmux-control-mode client. The client intercepts input lines beginning with
+`To:<registered-repo>:` line begins a block that closes on an empty line, a new
-`@<registered-repo>:` and submits a structured local message using the
+address, or worker exit; operator input is one addressed line. TAMQ preserves
-authenticated source window/repository. It does not wrap or replace the agent
+ordinary terminal bytes and records distinct worker/operator provenance.
-process. Control-mode parsing MUST preserve ordinary input unchanged and must
-not treat message-like text inside an unrelated multiline command as a message
-unless the configured parser recognizes a complete address line.
 
-If tmux control-mode interception is unavailable, tamq leaves ordinary terminal
+If observation is unavailable, TAMQ leaves ordinary terminal use unchanged and
-use unchanged, marks interception unavailable in status/receipts, and does not
+does not fall back to pane scraping. Operators may explicitly use
-fall back to pane scraping or unverified injection. Operators may explicitly
+`tamq send 'To:repo: message'` as a degraded path.
-use `tamq send @repo: message` as a degraded path.
 
 tmux-amq MUST retain a local message history sufficient to inspect delivery
 state and export it to a messages file. It MUST also support replaying a
@@ -171,17 +171,30 @@ override these defaults. The CLI MUST provide tab completion through
 options, and known gita repository targets.
 
 Version 0.1 supports direct addressing only. Unknown or unregistered targets
-are rejected; there is no broadcast or wildcard routing. If a target session is
+are rejected; there is no broadcast or wildcard routing. Coordination-engine
-absent, `tmux-amq` opens it and starts the configured command. The sender label
+resolves exactly one currently registered TAMQ endpoint for the target; zero is
-in the injected form is derived from the authenticated source repository, not
+unavailable and multiple matches require an explicit endpoint ID. It does not
-from message text.
+implicitly create a session or choose a pane occupant. The sender label is
+derived from the structured request or authenticated source window, not message
+text.
 
 Delivery acknowledgment is configurable and defaults to `injected`, meaning the
-message is considered delivered once tmux-amq successfully writes it to the
+message is considered transport-delivered once TAMQ successfully writes it to
-target PTY. An optional `acknowledged` mode retains the message until the target
+the target terminal. `acknowledged` enters `awaiting_ack` and redelivers the same
-agent explicitly confirms receipt; retries use the same message ID. This
+message ID after its deadline. Attempts, write failures, lease expiry, backoff,
-facility carries coordination messages, not task/workplan state. Substantive
+and terminal `failed` state are durable and bounded by the selected profile. A
-work, dependencies, and completion remain represented by State Hub facilities.
+late acknowledgement wins; terminal retry is explicit. Duplicate terminal
+presentation is possible and neither delivery mode proves agent comprehension
+or task completion.
+
+Coordination-engine uses its coordination lease ID as TAMQ's idempotency key and
+the trigger revision as correlation ID. Repeating an identical wake returns the
+original TAMQ message ID; reusing the lease ID for a different request fails.
+The client opens a new authenticated socket connection per operation, so
+receipt recovery after broker restart uses `message` or `history` rather than a
+connection session. If the bound endpoint disappears, repeating the identical
+wake may rebind the same durable message ID to its one replacement endpoint;
+TAMQ refuses implicit movement while the old endpoint remains live.
 
 Message bodies are human-readable UTF-8 plain text, limited to 8 KiB and
 preserving multiline content. The transport envelope carries structured IDs,