[BHAWESHBHASKAR]

Summary

This is the third PR of coordination Phase 2. It adds a feed of coordination events at GET /v1/events, read as a long-poll or a server-sent event stream: sessions starting, changing paths and ending, every land on a ref, and notes added, superseded and endorsed. A client can read from one server and resume on another without losing or repeating an event.

MCP agents now hear about a land on their files at their next tool call, not up to 30 s later. Orchestrators can watch the whole fleet with leep watch.

Why

Agents mostly learn things from the answers they already get, but some cases need a feed:

• an MCP agent between its own calls;
• an orchestrator watching many agents;
• a human running leep watch.

Polling /v1/notices every 30 s was the documented limit; this replaces it with a cheap "has anything relevant happened?" read.

Changes

Store: migration 0011_events, a logged table plus a one-row events_epoch.

• CoordStore gains append_events, events_after, events_bounds and sweep_events, on memory, SQLite and Postgres, with a contract test.
• Ordering:
  • On Postgres each append runs under pg_advisory_xact_lock, so commit order equals seq order, and events_bounds takes the same lock shared. Both set a 2 s lock_timeout, so a stuck writer cannot hold data-pool connections that lands share. The sequence is CACHE 1.
  • On SQLite, BEGIN IMMEDIATE and AUTOINCREMENT give the same order.
  • With the lock removed, the contract's test of concurrent writers and a reader failed 3 runs out of 3.
• Retention: 24 h (--events-retention, from 1 minute to 24 hours). The sweep removes the oldest prefix in seq order, running up to 5 s a minute. A new gauge, leep_events_oldest_age_seconds, shows how far it lags.
• Backups: events are not backed up. A restore renews the epoch, so an old cursor gets 410.

Events

• One row per fact. The kinds are:
  • session.started, session.paths (only when the set changes) and session.ended;
  • ref.landed, for every land, with the paths it changed;
  • note.added, note.superseded and note.endorsed.
• Events contain no prose: only ids, states, enum words and a 16-hex digest of the task key. Paths and the ref name sit under untrusted.
• The server holds events in a buffer of up to 10,000, flushes it every 250 ms, and counts any overflow. Failures are counted and never change an answer.

Route: GET /v1/events?after=&session=&paths=&kinds=&wait=

• Answers {events, next, more}, at most 500 events or 256 KiB.
• The cursor is opaque, e<epoch>.<seq>; the old e<seq> form is still accepted. A cursor that has expired, comes from another epoch, or points past the newest event gets 410 cursor_expired {oldest}.
• Long-poll: wait is clamped to 0–30 s and kept under the request timeout.
• Streaming: SSE with Accept: text/event-stream, Last-Event-ID to resume, a heartbeat every 15 s (which also re-resolves the session's paths) and a close after 10 minutes. A reader that falls behind gets event: reset.
• One tailer per server runs only while someone is waiting, feeding a ring of 10,000 events. A cold scan is capped at 8 pages per request.
• Admission:
  • A single parse decides whether a request waits, in the limits middleware and in the handler.
  • A waiter place (10,000 per server, 64 per principal; otherwise 503 Leep-Refused: events) is taken before any store work.
  • Waiting reads hold no ADR 0020 concurrency slot; rate limits still apply.
• session=KEY resolves only among the caller's own sessions. It matches other sessions' events on its paths or its task digest.

Clients

• CLI: leep watch [PATH...].
• MCP: each tool call with a session reads /v1/events?session=K&after=C&wait=0. It asks for notices on the first call, on a match, or on an expired cursor, and at least every 30 s as a floor, including when the events read fails. Against a server without events it keeps the 30 s poll.

Docs: ADR 0099, ARCHITECTURE §12, FORMATS, CLI.md, MCP.md, OPERATIONS (metrics, retention, migration 11 and rollback SQL, no backups), DEMO-COORDINATION.md (the 30 s limit is removed), the env example and changelog.d/coord-events.md.

Testing

• Lint and checks: fmt check, clippy -D warnings, check-version.sh and changelog-assemble.sh --check pass.
• Full suite: cargo test --workspace against Postgres 16 after merging main: 2,097 passed, 0 failed. The crash test passed 9/9.
• New tests:
  • Store: the contract checks ordering under concurrent appends, sweep bounds and the epoch, plus the v10 upgrade and snapshot tests.
  • Every land is an event: a land without agent.session, a stacked land, and a person's land over HTTP that matches an agent's session.
  • Admission: comes before any store work, against a store whose reads hang; the repeated-wait bypass is closed.
  • Expired cursors: a live ring still expires a cursor from elsewhere; a stuck event appender is refused after its lock timeout; long-polls stay bounded and clamped (on a paused clock).
  • Stream and caps: SSE resume and a slow-reader reset; the admission caps; cold scans are bounded.
  • Land equivalence: with a store that works except that append_events fails, appends are tried, nothing is stored, and land answers are unchanged.
  • MCP: a landed notice arrives on the next tool call, and notices are asked for at least every 30 s, including on 5xx.
  • Two servers: an e2e on SQLite and Postgres with writers on both servers and a reader that alternates between them sees every event exactly once, in order.
  • No agent prose appears in any event.
• No wall-clock asserts.

Fable reviewed the change and asked for four must-fixes before shipping. All four are in:

• every land is an event, and the 30 s notices floor is kept;
• admission is decided once, before store work;
• the ring answers 410 for a cursor past the newest event;
• the events lock has a timeout.

All the should-fixes (a land-equivalence store that truly fails appends, sweep throughput, bounded cold scans, store epochs, SSE scope refresh) and nits are in too.

Compatibility

• API: additive only. New route and types, new error code cursor_expired, new refusal value Leep-Refused: events, and new option --events-retention / LEEP_EVENTS_RETENTION.
• Migration 11 is additive. A v10 server refuses to start on a v11 database, as with every migration. The rollback SQL is in OPERATIONS.
• Branch history: the branch carries a merge of main (notes part 2, coord: note staleness, endorsement by human owners, and notes in context packs (ADR 0098) #284) and a no-op merge of its earlier, already-squashed history.

---

Generated by Claude Code