Authored by Claude Opus 4.7 (Claude Code). Session e748e6db-2785-414d-a13c-2ecbadbd221a.

FAIR-band: in-band [12/30] (canonical merged-count per gh search prs --merged --repo neomjs/neo --limit 30 --sort updated --json author 2026-05-19 post-#11600/#11606/#11607/#11610/#11611/#11612 merges; pending PRs #11614 + this PR not in count yet).

Resolves #11417.

Summary

Pre-fix add_message accepted any to: string and silently stored a null SENT_TO edge target when the value didn't match a registered AgentIdentity node. The MESSAGE node still retained the malformed value in its to: property, but the missing SENT_TO edge surfaced as to: null in get_message reads. Result: orphan messages invisible to the intended recipient, breaking cross-skill A2A coordination across /lead-role, /peer-role, /pull-request, and /pr-review.

Empirical anchor (per ticket body): ~17 A2A messages sent with alias-format to: "AGENT:<family>/<model>" (confab from the openapi schema's lone 'AGENT:*' example) silently orphaned in the 2026-05-15 session.

Changes — 3 independent improvements shipped together for substrate coherence

1. ai/services/memory-core/MailboxService.mjs — new validateMailboxTarget guard

New helper called after normalizeMailboxTarget and before the SENT_TO linkNodes call. Applies Option C from the ticket (resolve + reject):

• 'AGENT:*', role:, human: prefixes pass through unchanged.
• Targets matching a registered graph-node ID pass through. Cache-warm retry mirrors GraphService.linkNodes #10347 discipline.
• AGENT:<family>/<model> patterns resolve when exactly one AgentIdentity has matching properties.modelFamily + accountType: 'agent'.
• Ambiguous matches (multiple AgentIdentities sharing modelFamily) reject with an explicit error naming all candidates.
• All other unresolvable forms reject naming both the original + normalized values + the resolution policy.

Fires before the BLOCKED_BY / CAN_REPLY_TO permission checks so the failure surfaces as a substrate-level error rather than a permission-shaped one.

2. ai/mcp/server/memory-core/openapi.yaml — team-agnostic to: description

Replaces the bland one-liner "Recipient Agent Identity Node ID, or 'AGENT:*' for broadcast" with a single-line description (289 chars) naming the canonical @<identity> form, the 'AGENT:*' broadcast sentinel, and the AGENT:<family>/<model> alias-resolution policy. Per pr-review-guide §5.3 MCP-Tool-Description Budget audit (Cycle 2 update — see Cycle 2 entry below), the final shape describes call-site usage only: no internal cross-refs, no pre-fix archaeology, no ticket-number references in the schema payload. Placeholders use team-agnostic @<peer-agent> form (no @neo-opus-ada / @neo-gemini-pro / @neo-gpt identities hardcoded) per ticket Avoided Traps — framework substrate must remain forkable for client projects + downstream deployments.

3. Skill substrate worked-examples

Concrete add_message code-block examples added to 3 skill payload files with team-agnostic placeholders:

• .agents/skills/lead-role/references/lead-role-mode.md §2.2 — canonical to: '@<peer-agent>' shape for /peer-role skill-trigger delegation + anti-pattern showing the rejected alias confab.
• .agents/skills/peer-role/references/peer-role-mode.md §6.5 — [lane-claim] broadcast (to: 'AGENT:*') + targeted lane-pre-claim DM (to: '@<peer-agent>') examples.
• .agents/skills/pull-request/references/review-response-protocol.md §14 — author A2A handoff with explicit canonical to: '@<reviewer-agent>' form + commentId payload.

4. Regression test coverage

3 new tests under test.describe('#11417 add_message reject/resolve invalid to:') nested inside the outer suite so they inherit @alice / @bob / AGENT:* seed beforeEach:

• Reject path: 'AGENT:nonsense/blob' → throws Unrecognized 'to' format.
• Resolve path: 'AGENT:testfamily/anymodel' with single matching AgentIdentity → SENT_TO edge points at the resolved canonical identity; MESSAGE node's to: property reflects the resolved form (not the alias, not null).
• Ambiguous path: 'AGENT:multifam/anymodel' with two AgentIdentities sharing modelFamily → throws Ambiguous 'to' alias.

5. Incidental whitespace cleanup

Stripped pre-existing trailing-whitespace lines in MailboxService.mjs, MailboxService.spec.mjs, and openapi.yaml to clear the husky check-whitespace pre-commit gate. Mechanical hygiene; no logic changes on those lines.

Cycle 1 (8393cb629) — pre-existing test fixture gaps fixed

GPT's [review-hold] (MESSAGE:29aefd39) surfaced 2 pre-existing test fixtures that exercised the silent-null orphan bug behavior (passing only because the validator wasn't yet in place):

• WriteSideInvariant.spec.mjs:117 — sent to @neo-test-receiver while only seeding @neo-test-writer + AGENT:*. Fix: added GraphService.upsertNode for @neo-test-receiver (3/3 PASS verified locally).
• trioWakeCooldown.spec.mjs — subprocess sent to placeholder @neo-test. Initial Cycle 1 fix tried fixture-process beforeAll seeding, but UNIT_TEST_MODE='true' → graph storage is :memory: per-process per config.template.mjs:214, so fixture seeds never reached the subprocess.

Cycle 2 (d491a50b5) — canonical-identity fix + openapi compaction

Per GPT's [review-hold] (MESSAGE:ed55919e):

• trioWakeCooldown.spec.mjs: replaced @neo-test with TEST_COORDINATOR = '@neo-opus-ada' (canonical identity that seedAgentIdentities.mjs provisions at the subprocess's LifecycleService.initAsync). Removed the useless fixture-process beforeAll.
• openapi.yaml to: description: compacted from multi-line block-literal (with internal #11417 reference + pre-fix archaeology) to single-line (289 chars, well under 1024 cap). Removed internal ticket cross-ref per pr-review-guide §5.3 MCP-Tool-Description Budget audit. Describes call-site usage only: canonical @<identity> form + AGENT:* sentinel + alias resolution policy.

/turn-memory-pre-flight Retrospective Audit

(Documented retrospectively per @neo-gpt Cycle 1 pre-flagged audit gap on PR body. The 3 modified .agents/skills/**/references/*.md files are skill-loaded substrate; the audit mandates explicit decision-tree application + harness-load-duplication risk audit.)

Substrate-load surface

Decision-tree application (per ADR 0007 disposition taxonomy)

Harness-load-duplication risk audit

• No duplicated prose: each worked-example lives in ONE canonical location per skill. The 3 examples target different skill surfaces (lead/peer/pull-request) without redundancy.
• No cross-harness substrate: .agents/skills/ is harness-agnostic (loaded uniformly by Claude Code / Antigravity / Codex Desktop per the symlink + .codex/hooks.json patterns from #10440). No harness-specific behavioral fork introduced.
• No always-loaded Map substrate: this PR does NOT modify AGENTS.md / AGENTS_ATLAS.md / AGENTS_STARTUP.md / .agents/ANTIGRAVITY_RULES.md. The substrate-load impact is per-skill-invocation, not per-turn.

Pre-flight mechanical commands

node ai/scripts/lint-agents.mjs --base origin/dev      # OK — no <a id> regressions
node ai/scripts/check-substrate-size.mjs               # PASS — AGENTS.md unchanged
node buildScripts/util/check-whitespace.mjs            # PASS
git diff --check origin/dev...HEAD                     # PASS

Future-session bias prevention

The worked-examples use team-agnostic placeholders (@<peer-agent>, @<reviewer-agent>) per ticket Avoided Traps — framework substrate must remain forkable. No @neo-opus-ada / @neo-gemini-pro / @neo-gpt identities hardcoded into framework substrate. Client projects + downstream Neo deployments have their own AgentIdentity registries; the examples remain portable.

Slot Rationale (per pull-request-workflow §1.1 substrate-mutation gate)

Modified substrate (mixed: code + Map + skill):

• ai/services/memory-core/MailboxService.mjs — runtime service code (substrate gate)
• ai/mcp/server/memory-core/openapi.yaml — MCP tool schema (description)
• .agents/skills/lead-role/references/lead-role-mode.md — skill payload (worked-example)
• .agents/skills/peer-role/references/peer-role-mode.md — skill payload (worked-example)
• .agents/skills/pull-request/references/review-response-protocol.md — skill payload (worked-example)
• test/playwright/unit/ai/services/memory-core/MailboxService.spec.mjs — regression coverage

Disposition deltas (per ADR 0007 taxonomy):

• MailboxService.mjs — keep (new substrate-level guard; no existing logic retired)
• openapi.yaml — rewrite (description expanded with failure-mode naming + resolution policy)
• 3 skill payloads — keep (worked-examples added; existing prose unchanged)
• spec file — keep (3 new tests + incidental whitespace cleanup)

3-axis rating:

• Trigger-frequency: every add_message call across every cross-skill A2A handoff — VERY HIGH
• Failure-severity: orphan messages invisible to recipients = broken cross-family coordination = swarm dead air (operator-empirical 2026-05-15: ~17 orphaned messages in a single session) — HIGH
• Enforceability: substrate-level guard at the MCP boundary; rejects malformed to: mechanically; alias-resolution path tolerates common confab patterns without sacrificing fail-loud semantics — VERY HIGH

Decay mitigation: the guard fires at the substrate boundary (single chokepoint) and uses real graph-node state for V-B-A; no parallel rule-table to drift. Skill worked-examples reference @<peer-agent> placeholders so framework forkability is preserved. Substrate-correctness is enforced by the 3 regression tests under the canonical describe identifier.

Architectural Impact

• No runtime surface change for valid calls — existing canonical @<identity> / 'AGENT:*' paths unchanged; behavioral parity for all already-working production code.
• Failure-mode visibility — pre-#11417 silent to: null orphans now surface as Unrecognized 'to' format errors with concrete remediation in the message (canonical form named, alias policy explained).
• Substrate-forkability preserved — no neo-X identities hardcoded into framework substrate; clients/forks can have their own AgentIdentity registry.
• Cross-skill A2A coordination unblocked — /lead-role, /peer-role, /pull-request, /pr-review no longer silently lose messages when an agent confabulates the alias form.

Edge Cases

• role: and human: prefixes pass through unchanged: legacy addressing forms; if they target orphan nodes the FK guard surfaces that separately — this validator scopes to the @<identity> + AGENT:<family>/<model> failure surface documented in #11417.
• Cache-warm retry on missing endpoints: mirrors GraphService.linkNodes #10347 discipline — the guard does NOT reject targets that exist in WAL but haven't synced to the in-memory cache yet.
• Single-match alias resolve: AGENT:claude/opus against a graph with exactly one modelFamily: 'claude' AgentIdentity → resolves to that identity. Both the SENT_TO edge AND the MESSAGE node's to: property carry the resolved canonical form (no alias leakage downstream).
• Multi-match alias reject: forbids the implicit "pick arbitrarily" path that would silently route to whichever node happens to come first in iteration order.
• Permission interaction: validator fires BEFORE BLOCKED_BY / CAN_REPLY_TO checks — failure surfaces as substrate-level format error, not a misleading permission-denied error.

Test Evidence

Cumulative across Cycles (final state at head d491a50b5):

• npm run test-unit -- MailboxService.spec.mjs --grep #11417 → 3/3 PASS (802ms) — new reject / resolve / ambiguous regression tests
• npm run test-unit -- MailboxService.spec.mjs WriteSideInvariant.spec.mjs → 62/62 PASS (1.4s, Cycle 2 head) — full Mailbox suite (59) + WriteSideInvariant (3) with @neo-test-receiver fixture seed
• npm run test-unit -- TextEmbeddingService.retry.spec.mjs cross-checked clean (unrelated to this PR; ran as part of broader sweep verifying no regressions)
• node ai/scripts/lint-agents.mjs --base origin/dev → OK
• node ai/scripts/check-substrate-size.mjs → PASS (AGENTS.md unchanged)
• node buildScripts/util/check-whitespace.mjs → PASS
• git diff --check origin/dev...HEAD → PASS
• Pre-commit hook (husky → lint-staged → check-whitespace) → PASS (Cycle 2)
• GitHub CI (head d491a50b5): all green expected; canonical verification surface for cross-process subprocess test fix (trioWakeCooldown.spec.mjs) since fixture-process can't reach the subprocess's :memory: graph DB.

Focused-spec caveat (deferred to follow-up #11617): standalone npm run test-unit -- test/playwright/unit/ai/scripts/trioWakeCooldown.spec.mjs fails before discovery with TypeError: Neo.ns is not a function at test/playwright/setup.mjs:73 — a pre-existing test-infra gap introduced by PR #11578's setup mock requiring prior Neo import in the worker. Full CI passes by worker-order side effect (workers: 1 keeps prior-spec Neo load persistent). Filed as #11617 per @neo-gpt; out-of-scope for this runtime guard PR.

Evidence: L2 (runtime guard + regression coverage at sandbox ceiling — local Playwright unit specs + GitHub CI). L3 (live Memory Core MCP roundtrip post-merge) is the production verification surface; not gated here.

Cross-Family Review Mandate

Per pull-request-workflow.md §6.1. Requesting @neo-gpt as primary reviewer — Gemini benched per operator-direction. V-B-A focus areas:

1. Alias-resolution policy soundness: AGENT:<family>/<model> → single AgentIdentity by modelFamily. Right resolution surface? Alternative: lookup by <model> part directly (e.g. AGENT:openai/gpt-5.5 looks up name: 'GPT-5.5')? I chose modelFamily because it's the stable property; model-name strings are version-volatile.
2. Permission-check ordering: validateMailboxTarget runs BEFORE BLOCKED_BY / CAN_REPLY_TO. So a sender with BLOCKED_BY AND a malformed to: sees the format error first, not the block. Right precedence?
3. role:/human: prefix pass-through: I deliberately scoped this validator to @<identity> + AGENT:<family>/<model> patterns (the actual failure surface per #11417). Legacy role:/human: prefixes pass through. Right boundary?
4. Migration of historical orphans: Out of Scope per ticket. I did NOT add an audit/migration script. If you think one should land in this PR, surface that — otherwise I'll file a separate follow-up ticket if/when forensic preservation needs surface.

Requested action: use /pr-review on this PR.

Post-Merge Validation

• First cross-skill A2A handoff post-merge does NOT produce orphan messages (verify via get_message({messageId}) returning concrete to: value, not null)
• Confabulated alias attempts (any sender re-deriving to: after compaction) reject with the new error rather than silently orphan
• AGENT:<family>/<model> resolution path observed in production for at least one cross-family A2A (substrate-evidence the resolve path is exercised, not just the reject path)

Deltas from ticket

One explicit out-of-scope deferral (per ticket's own "Out of Scope" section): historical alias-format orphan records → no audit/migration script in this PR. Forensic-preservation migration deferred to a separate follow-up ticket if/when operator surfaces that need. The validator catches new orphans going forward; historical orphans remain visible only via direct graph inspection (no automated cleanup pass shipped).

AC closure status:

• ✅ openapi.yaml add_message.to description updated (team-agnostic, single-line, §5.3 budget-compliant after Cycle 2 compaction)
• ✅ 3 skill files (lead-role-mode §2.2, peer-role-mode §6.5, review-response-protocol §14) carry concrete A2A worked-examples with team-agnostic placeholders
• ✅ add_message with unresolvable to: rejects with clear error OR resolves to canonical identity (Option C — both paths)
• ⏸ DEFERRED to follow-up: existing alias-format orphan records (per ticket "Out of Scope" — forensic-preservation migration script). Will file follow-up ticket when operator surfaces that need OR when audit-time grows large.
• ✅ Spec coverage for new behavior (reject path + resolve path + ambiguous path; 3/3 PASS via MailboxService.spec.mjs #11417 describe block)
• ✅ Cycle 1 + 2 follow-on: pre-existing test fixture gaps (WriteSideInvariant.spec.mjs + trioWakeCooldown.spec.mjs) surfaced + fixed by Cycle 1/2 commits; not in original AC, but substrate-correct cleanup that the new validator forced
• ⏸ DEFERRED to #11617: standalone ai/scripts/ focused-unit setup failure (Neo.ns is not a function at setup.mjs:73) — separate test-infra concern from PR #11578, filed by @neo-gpt

Related

• Source ticket: Resolves #11417
• Substrate authority: ADR 0007 (Map vs World Atlas compaction taxonomy — skill worked-examples land in skill payloads, not in turn-loaded AGENTS.md)
• FK-cull bug class: #10174 (original SENT_TO cull bug; this PR closes the alias-confab subclass)
• Observability log: Phase 1 #10347 SENT_TO observability log surfaced the empirical confab pattern; this PR moves from observability → substrate guard
• Operator-direction: in-session 2026-05-15 (~17 orphan-message anchor); ticket body authored 2026-05-15