mailboxMisrouteNote function

String mailboxMisrouteNote(List<MailboxEntry> entries, String targetId)

The cross-root misroute diagnostic for a send resolved to targetId (issue #516). Returns '' when the id maps to fewer than two mailboxes — the normal case; an asleep target stays silent because offline queueing is the contract (#402). When the same id owns mailboxes under SEVERAL project roots, the sender learns where delivery landed instead of silently queueing: the live registration's root is named and stale corpses are called out, or — when no root holds a live registration — the named misroute warning fires.

Implementation

String mailboxMisrouteNote(List<MailboxEntry> entries, String targetId) {
  final matches = entries.where((entry) => entry.id == targetId).toList();
  if (matches.length < 2) return '';
  String where(MailboxEntry entry) => entry.cwd ?? entry.slug ?? 'unknown root';
  final live = matches.where((entry) => entry.isConfirmedLive).toList();
  final stale = matches.where((entry) => !entry.isConfirmedLive).toList();
  if (live.isNotEmpty) {
    final ignored = stale.map(where).join(', ');
    return ' Delivered to the live mailbox under ${where(live.first)}'
        '${ignored.isEmpty ? '' : '; stale mailbox under $ignored ignored'}';
  }
  return ' warning: mailbox exists under project '
      '${matches.map(where).join(', ')} but the agent is not live '
      'anywhere — queued offline';
}