TermAl

Agent Coordination Boards

Small, versioned JSON facts scoped to one local project, shared by that project’s root sessions. The board is level-triggered state — durable truth that peers read at their own pace — and is the deliberate complement of durable agent mailboxes, which carry edge-triggered events that wake sessions. Board writes never wake anyone: if a change needs someone’s attention now, send a mailbox message pointing at the key.

Tracker: tm-uwx.7 (design v1.1 on the bead records the negotiated contract with code citations). Store: src/coordination_board.rs. HTTP surface: src/board_routes.rs. MCP tools: src/delegation_mcp.rs (termal_board_list / termal_board_get / termal_board_set).

Board tables live beside mailbox tables in ~/.termal/coordination.sqlite. Both stores retain one long-lived connection and share coordination-local FIFO writer admission, isolated from termal.sqlite session/transcript persistence.

Model

• Scope = one local project (project.id). Callers never name the scope; it is derived from the calling session’s project. Sessions without a project, hidden sessions, delegation children (by parent marker OR the durable delegation index — independent evidence sources), remote proxies, and sessions in remote projects are all rejected by the backend itself; MCP tool filtering for delegation children is defense-in-depth on top.
• Entry = dotted key → JSON value with a per-key revision (starts at 1), updatedAtGeneration (the scope generation when that key was last written), plus author, timestamp, and optional stateStamp.
• Generation = scope-wide counter bumped once per successful non-duplicate write. List responses expose the current value as generation; single-key reads expose it as scopeGeneration, distinct from the key’s historical updatedAtGeneration. Only the current scope value is valid as knownGeneration or snapshotGeneration.
• Keys: 1–8 dotted segments, each starting [a-z0-9] then [a-z0-9_-]*, ≤128 bytes total (e.g. activity.rust-suite, freeze.fingerprint).
• Values: canonical JSON (sorted object keys), ≤4096 bytes encoded, depth ≤32. null is a legitimate value, distinct from deletion.

Write semantics (CAS + idempotency)

Every write carries expectedRevision and an author-scoped idempotencyKey.

Intent	Input	Against	Result
Create	expectedRevision: 0 + value	never-existed key	revision 1
Create	expectedRevision: 0 + value	live head or tombstone	409 with current head / tombstone revision in detail
Update	exact live revision + value	matching head	revision +1
Restore	exact tombstone revision + value	tombstoned key	revision +1 (conscious resurrection — the only way back)
Delete	exact live revision + delete: true (no value)	matching head	tombstone, revision +1
Delete	exact tombstone revision	tombstoned key	404 “already absent”
Delete	mismatched revision	tombstoned key	409 with the tombstone revision in detail
Delete	any revision	never-created key	404

• expectedRevision: 0 is strictly create-only. It never resurrects a deleted key — that guards against ABA: a stale pre-creation writer cannot silently undo a deliberate deletion. Restoration requires reading the tombstone’s revision from the 409 detail and CAS-ing against it.
• Revisions never reset. Tombstones persist (values stripped) so the CAS token space is stable forever.
• Idempotency: the lookup namespace is scope + author session + idempotencyKey (the board key plays no part in the lookup). Replaying the identical full request — same key, value, expectedRevision, and stateStamp — returns the original receipt with duplicate: true; reusing the same idempotencyKey for any different intent → 409. Receipts survive history compaction inside the bounded 4,096-write replay window described below.
• On the wire, deletion is delete: true with the value field absent — JSON cannot express the difference between “value: null” and “no value”, so the discriminator is explicit.
• Typed storage-busy rejections distinguish writes (“…no coordination board write was committed by this operation…”) from reads (“…no mutation was attempted by this read operation…”). Both prove exact-request replay is safe; the delegation-MCP bridge retries them automatically with bounded, session-jittered backoff (tm-uwx.7.4). Repeated 503s after that mean sustained contention, not corruption.

Read semantics

• get and list never return deleted keys as entries; “never existed” and “deleted” are both 404 on read, but a get 404 for a deleted key may carry the tombstone head (revision, deleted: true, structurally null value) in its detail — the same restore token write conflicts expose.
• A successful get returns both updatedAtGeneration (when that key last changed) and scopeGeneration (the scope’s current counter). These values intentionally diverge when another key was written later.
• list is sorted by key, default page 100 / max 200, and is generation-bound: page continuations carry snapshotGeneration, and any mutation between pages yields 409 — restart the listing. A busy scope larger than one page can therefore livelock a listing; accepted for v1 because expected scale is well under one page (the 512-live-key cap bounds the returned set).
• knownGeneration on a first page returns unchanged: true with zero rows when nothing moved — the O(1) turn-start check.

Limits and lifecycle

• 512 live keys and 4,096 lifetime distinct key names per scope. Tombstones retain their ABA-safe revision tokens but do not consume live capacity, so deleting a fact frees a live slot. Restoring a retained tombstone reuses its distinct-name slot but still consumes a live slot and is rejected while all 512 are occupied. A brand-new name is rejected after 4,096 distinct heads, so ephemeral key churn cannot grow the scope without bound; reuse stable names or delete the project to clear the whole scope.
• History: last 100 revisions per live key (excluding the current head). Deleting a key purges its historical values while retaining the single tombstone head and revision needed for ABA-safe restoration.
• Idempotency: latest 4,096 successful writes per scope, ordered by durable insertion rather than wall-clock timestamps. This bounded replay window comfortably covers transport-loss retries without making the receipt table grow forever. Within the window, the exact original receipt is replayed. Once a receipt ages out, monotonic revisions and tombstones still prevent the old request from being silently applied again, but the caller receives the current CAS outcome rather than the historical receipt.
• Scope deletion happens only through a crash-consistent project-deletion outbox. The project removal and pending cleanup first land in termal.sqlite; only then does a dedicated cleanup worker install an idempotent deletion fence and cascade the scope in coordination.sqlite. Unfinished outbox entries are scheduled again on boot. Any cleanup failure stays durably queued; the already-absent project prevents HTTP callers from authorizing new work for that scope in the meantime. The fence rejects any already-authorized stale write that arrives after cleanup. Lifecycle cleanup uses a short coordination-admission budget, and the cascade runs outside both boot and the primary persist worker. A busy or large secondary scope therefore cannot delay the HTTP listener or primary session persistence. There is deliberately no agent-facing scope wipe: it would bypass per-key CAS and erase the tombstones and receipts the safety model depends on.
• The coordination-side deletion fence is permanent and grows by one row per deleted project. Newly created projects use UUID-backed ids, so a future project cannot inherit either the deleted scope’s fence or its former facts after the primary database is restored or reset.
• The coordination board currently has no human-facing panel. Agents access it through the termal_board_* MCP tools or the project-scoped HTTP routes. This keeps its level-triggered coordination role distinct from the visual Response Board, which stores immutable transcript-card snapshots for a human workspace.
• Newly created projects use collision-resistant project-<uuid> ids. Existing persisted ids remain valid, but a restored/reset termal.sqlite cannot reuse the rewindable legacy counter and accidentally inherit a live board scope or permanent fence from the independently durable coordination.sqlite.
• Local-authoritative v1: the board exists only on the local instance; remote projects and proxies are rejected and nothing syncs. Any future remote story must be explicit, not incidental.

Relationship to mailboxes

	Mailbox (doc)	Board (this doc)
Trigger model	Edge — messages activate sessions	Level — facts sit still
Ordering	Dense per-mailbox sequence, FIFO	Per-key revisions + scope generation
Read discipline	Cursor CAS (processedThrough)	Plain reads; CAS only on write
Wakes the peer	Yes (metadata-only notification)	Never
Typical use	“Review round 2 is ready for you”	activity.rust-suite, freeze fingerprints, gate status

Convention: coordinate who does what next through the mailbox; publish what is currently true on the board. A mailbox message may simply say “board key gates.union changed — read it when convenient.”

See SQLite session storage for the two-database layout, migration, and boot ordering.