openclaw - 💡(How to fix) Fix feat(gateway): add createOnMiss=false (strict mode) for sessions_send / sessions_spawn

Summary

Request a create-on-miss=false (or equivalent strict-mode) configuration knob on sessions_spawn / sessions_send / session-key resolution paths, so unrecognized session keys fail fast instead of silently spawning a phantom session.

Motivation (incident-driven)

On 2026-05-11, a Peggy → Atlas sessions_send call addressed to a malformed Atlas session key (agent:atlas:telegram:atlas:direct:6596143250) silently created a phantom Atlas session parallel to the canonical agent:atlas:main. This produced a multi-hour split-brain where Peggy and Atlas were posting into two different sessions, with neither aware of the other. Full audit at audit/atlas-split-brain-2026-05-11/ in our workspace (PCCA / Dev in a box internal).

Root cause (verified against OpenClaw 2026.5.7 at dist/sessions-helpers-D-D4T8Yk.js): resolveSessionReference returns ok: true for any non-empty sessionKey string without an existence check; the subsequent agent dispatch then spawns the new session on first message. Caller-side guards can mitigate (and we have implemented scripts/atlas/peer_send.py to do so), but the runtime invariant is the right place for this protection.

Proposed knob

{
  "gateway": {
    "sessions": {
      "createOnMiss": false   // default: true (current behavior, backward compatible)
    }
  }
}

When createOnMiss: false:

• sessions_send(sessionKey: "...") and sessions_spawn(sessionKey: "...") MUST verify the key resolves to an existing session before dispatch.
• If the session does not exist, return a structured error (e.g. SessionNotFoundError) with the requested key.
• Do NOT spawn implicitly.

Why this matters beyond our incident

• Any production-grade multi-agent system that routes by session key needs the option to fail closed.
• Caller-side guards (like our assert_atlas_send_target) only catch the calls that go through them. New code paths, new agents, and new operators have a recurring failure surface until the runtime supports strict-mode.

Acceptance criteria

1. New config flag gateway.sessions.createOnMiss (or equivalent, naming open) honored by both sessions_send and sessions_spawn.
2. When set to false, dispatching to an unknown session key returns a structured error rather than spawning.
3. Default remains true for backward compatibility.
4. Documented in docs/gateway/configuration-reference.md.

References

• scripts/atlas/peer_send.py in our workspace — caller-side guard pattern, fails closed, audits orphan attempts to ~/.openclaw/audit/atlas-peer-send.jsonl.
• ADO #15558 (PCCA / Dev in a box, internal) — this same enabler tracked on our side.
• dist/sessions-helpers-D-D4T8Yk.js in OpenClaw 2026.5.7 — current resolveSessionReference source.

Versions

• OpenClaw: 2026.5.7
• Reporter: PCCA / Dev in a box (Marcio Esteves, Peggy agent team)