[BHAWESHBHASKAR]

Summary

This is the first PR of coordination Phase 2. Agents and people can now leave notes: a finding, a gotcha, a decision or a how-to, anchored to a path or a changeset, for the next agent working there. Each note carries:

• a trust tier taken from the token, with a new kind: agent|human field in the tokens file;
• caps on size, count and rate, plus expiry;
• an attributed report flow with an operator undo.

All agent-written text stays inside the untrusted fence.

PR 2, still to come, adds staleness, endorsement by human owners and a notes section in the context pack. The maintainer decided that only human owners may endorse a note, that notes go into backups, and that the session-head GC root is deferred.

Why

Agents keep rediscovering the same facts ("this test needs the cache warmed", "don't touch this file without telling billing"). Notes let them hand those facts to the next agent on the same files. Notes are also the largest new surface for prompt injection, so this PR is mostly limits and fencing.

Changes

Store and migration 0010_notes (memory, SQLite and Postgres; contract-tested)

• One notes table holding:
  • the kind and the anchor (a path or a changeset);
  • at_changeset and at_blob, and an optional line range;
  • the title and body;
  • the principal, agent_model and session_id;
  • trust, endorsed_by and endorsed_at (PR 2 writes these);
  • state, superseded_by, reported_by and reported_at;
  • created and expires.
• Indexes on the anchor and the principal, a partial index on open notes per principal, and one on reports.
• A new note can supersede one of the author's own open notes in the same transaction. Superseding someone else's note answers 403; superseding a note that is no longer open answers 409.

API (additive)

• POST /v1/notes, which returns a NoteEntry. Everything an agent wrote (title, body, anchor and agent_model) is under untrusted.
• GET /v1/notes, filtered by path (which matches the path and the directories above it), changeset, principal, mine or state, with paging.
• GET /v1/notes/{id}; DELETE /v1/notes/{id}, which the author uses to retract.
• POST /v1/notes/{id}/report.

Limits

• Size: a title is one line of at most 200 bytes; a body at most 4,096 bytes; a path anchor at most 256 bytes. A listing path over 256 bytes is refused.

• Characters refused at write: C0 and C1 controls (the body may contain only \n), U+2028/2029, bidi controls and marks, zero-width characters, U+FEFF, U+2060–206F and Unicode tag characters.

• Per principal:

  • 200 open notes (400 too_many_notes);
  • 30 an hour and 100 a day (429 rate_limited with Retry-After).

  On Postgres the caps are exact under a per-principal advisory lock with a 2 s lock timeout (503, Leep-Refused: note-lock). On SQLite they are exact through BEGIN IMMEDIATE.

• Expiry: an agent note expires after 90 days and a human note after 365. A closed note is deleted 30 days after it closes. The existing per-minute sweep does this, bounded by HOOK_TIMEOUT.

Trust: human when the writing token has kind: human, otherwise agent. Nothing in a request can set trust. Upgrade every server before a tokens file uses kind, because the file rejects unknown fields. The upgrade order is in OPERATIONS.

Reports

• Any writer may report a note, which hides an agent note. The report is attributed (reported_by, reported_at) and logged by note id and reporter, never the note text.
• A reporter can hide at most 30 notes an hour (429).
• An operator can undo reports with leep-server notes unreport --id N | --reporter P, and remove a principal's notes with notes revoke.

Clients

• CLI leep note add|list|show|retract|report; agent text and non-plain token names are escaped.
• MCP leep_note_add and leep_notes (with paging), which brings the tool count to 26. Outside the fence MCP shows only the id, kind, principal, trust, state and supersession.

Backups: notes are included, unlike sessions. Restoring resets the id sequence. A restored note's session_id is informational and may point to a session the restore does not have.

Docs: ADR 0098, ARCHITECTURE §12, FORMATS, CLI.md, MCP.md, DEPLOY.md, OPERATIONS (metrics, migration 10, the order for adopting kind, revoke and unreport, backups, worst-case storage of about 15 MiB per principal) and changelog.d/coord-notes.md.

Also: the wall-clock test a_hanging_coordination_store_changes_no_answer (it asserted under 300 ms against a 250 ms bound and flaked) is split in two:

• one test checks the answers and ref logs, inside a 10 s liveness timeout;
• one checks the bound exactly on a paused tokio clock.

Testing

• Lint and checks: fmt check, clippy -D warnings, check-version.sh and changelog-assemble.sh --check all pass on this head.
• Full suite: before the merge with main, cargo test --workspace against Postgres 16 passed 2,023 tests with 0 failures. A full run on the merged head is in progress locally, and CI runs it too.
• New tests:
  • the notes store contract on all three stores, including 16 concurrent supersedes with one winner, every cap, and a bounded sweep;
  • upgrade_from_v9_adds_notes;
  • backup round trips (SQLite, Postgres→SQLite→Postgres, restoring a v9 snapshot);
  • router tests for 403s and every cap, plus a Postgres test that holds the lock from another connection;
  • injection fixtures on the server, MCP and CLI, including a refused agent_model. They strip untrusted and check that no planted string remains, and that refused strings are never echoed;
  • the land-equivalence property test now writes, supersedes, reports, retracts and sweeps notes between lands;
  • CLI end-to-end tests on SQLite and Postgres.
• No wall-clock asserts.

Fable reviewed the change and returned "ship after must-fixes". The three must-fixes are in:

• the unbounded listing path;
• agent_model moved under untrusted;
• reports attributed, capped and undoable.

So are all the should-fixes and nits.

Compatibility

• API: additive only; there are new routes and types.
• Tokens file: kind is optional and absent means agent. A file without it fingerprints the same as before.
• Migration 10 is additive. A v9 server refuses to start on a v10 database, as with every migration, and the rollback SQL is in OPERATIONS.
• New refusal reason: Leep-Refused: note-lock.
• Branch history: this branch carries a merge of main (the pre-flight check from mcp: stop a land for overlaps the agent has not seen (pre-flight) #282) and a no-op merge of its earlier, already squashed history, so the diff holds only this change.

---

Generated by Claude Code

[BHAWESHBHASKAR]

The first perf run on f5a7452 failed one wall-time check: swarm land p99 was 2.57x (B 255/436 ms vs A 146/123 ms). Every count and work-per-land check passed; statements, bytes and batch size were flat or lower.

Re-running the job once on the same head passed every check. A local A/B against main also passed all 23 checks (0 failed, 1 inconclusive), though that box was loaded and one of its A runs was noisy.

The change adds nothing to the land path. Its only new periodic work is a notes sweep bounded by HOOK_TIMEOUT. I'm treating the first run as runner noise in a wall-time ratio and merging on the green re-run.

---

Generated by Claude Code