[BHAWESHBHASKAR]

Summary

This PR fixes five frictions that the twenty-agent coordination demo (#280) surfaced in Phase 1 notices and context packs. It also includes the fixes from a Fable review of those changes. The demo now has nine claims; three are new and each checks a fix.

Why

The demo showed agents being told the wrong thing, or nothing:

• A pack said [same_file] (your "src/api/handlers.rs") while the notice for the same overlap said [near].
• The first agent of a duplicate pair was never told about the second.
• Agents that never declared a session did not hear about lands.
• A duplicate's land was not labelled as one.
• Packs repeated the same owners and history rows for every co-changed file.

Changes

Friction fixes

1. Packs rank overlaps by the agent's own paths. The level comes from the request's paths and the session's own paths. Work met only on a co-changed or searched file gets the new optional Notice.via: "related", ranks after the agent's own overlaps, and never counts toward a crowded path. The CLI renders it as "a file related to your task".
2. The first of a duplicate pair is told. The task-key lookup now runs on creates, lands, /v1/notices and listings, not only on declaration. It is still said once, and an agent restarting under a new key is still not flagged.
3. Undeclared sessions hear about lands.
   • A new optional request header, Leep-Target-Ref, on POST /v1/changesets.
   • The CLI sends its working copy's target ref, and leep_commit_and_land sends its target_ref.
   • An inferred session follows the ref each commit names. A declared target is never overridden.
4. A duplicate's land is labelled. The notice reads by: task_key: "your duplicate landed this task; check whether your work is still needed".
5. Quieter packs.
   • Owners and history rows are grouped across files (untrusted.paths), and bytes is measured after grouping.
   • MCP explains a carry rule once per pack.
   • leep_task_start and leep work start drop any notice the pack already shows.

Review fixes (Fable: ship after must-fixes, all applied)

• Every land of a duplicate session is its own notice, and the session's live overlap still shows beside it.
• A failed task-key listing drops only the pack's duplicates section; in_flight stays.
• A land whose creator cannot be read is never tagged as a duplicate's. Without this, a forged agent.session could earn the tag.
• A task key's live sessions (at most 40) and landed sessions (at most 64) are read separately, so landed history never hides a live duplicate.
• A revived session forgets its task key and target ref.
• New server setting --default-ref (LEEP_DEFAULT_REF, default main): sessions with no target are checked against it. The notice says so through the new optional Notice.landed_on, as in "landed on main".
• Demo claims tightened:
  • claim 7 requires a pack line and a positive "related file" line;
  • claim 9 requires exactly one carry explanation;
  • claim 2 requires cy's warning to come from cy's own pack;
  • an e2e leep status check now retries instead of running once.

Docs: ADR 0095, 0096 and 0097 amended; FORMATS ("Notice and pack refinements"), ARCHITECTURE §12, CLI.md, MCP.md, OPERATIONS, DEMO-COORDINATION.md and the env example updated. Changelog fragment: changelog.d/coord-demo-friction.md.

Testing

• Lint and checks: fmt check, clippy -D warnings, check-version.sh and changelog-assemble.sh --check pass on this head.
• Full suite: cargo test --workspace against Postgres 16, including leep-e2e, passed on the fixer's tree before its last commit. That commit only added LEEP_DEFAULT_REF to the env example; leep-server and leep-cli were rerun after it. A full rerun on this head is in progress locally, and CI runs it too.
• One test per fix, and each failed before its fix. One exception: the default-ref test needs the new setting to exist, so it can't run against the old code. Examples:
  • related_files_never_outrank_my_own
  • the_first_of_a_duplicate_pair_is_told_too
  • an_undeclared_session_hears_of_lands
  • a_duplicates_land_is_named_as_such
  • identical_owners_and_history_rows_are_one_item
  • each_land_of_a_duplicate_is_its_own_notice
  • a_failed_task_key_listing_keeps_live_work
  • landed_sessions_never_hide_a_live_duplicate
  • a_revived_session_forgets_its_task_and_ref
  • a_session_without_a_target_hears_of_the_default_ref
• Demo: all nine claims pass on SQLite and Postgres, at the default search concurrency and with --read-concurrency search=1.

Compatibility

• API: additive only. New optional fields Notice.via and Notice.landed_on, and the optional Leep-Target-Ref request header.
• Older clients:
  • they read only untrusted.path, so they see the first file of a grouped item;
  • they don't send the header, so their inferred sessions are checked against --default-ref.
• Visible changes:
  • the first of a duplicate pair now hears possible_duplicate where it used to hear claimed or same_file;
  • notices already shown in a task-start pack are not repeated.
• No migration.
• Known limits, left for the maintainer (in DEMO-COORDINATION.md):
  • leep_commit_and_land delivers create-time notices only after the land;
  • the MCP 30 s notice poll;
  • a shed pack at leep_task_start is not retried by the tool.
• Branch history: the branch carries a no-op merge of its earlier history (e2e: twenty-agent coordination demo, and two fixes it found #280, squashed into main as 74c86f0), so this diff holds only this change.

---

Generated by Claude Code