Route local wake delivery through a signed Shape-B dispatcher

Context

This is the graphless host-edge prerequisite for neomjs/neo-agent-brain#84, which hard-cuts the operator's machine to the Docker-canonical Agent OS and then deletes the obsolete local plane.

At the verified baseline 41f3c317a5a8f38ef8cebf6a781fd67093628c77, the host wake daemon still imports the graph query layer and better-sqlite3, opens the graph database, and mutates Nodes. The current neomjs/neo-agent-brain#84 cutover overlay would therefore leave a host process sharing graph storage with the container-owned Memory Core. That is not single-writer ownership; it is the old Shape-C worker crossing the new container boundary.

The operator constraint is deliberately narrow: one machine, one hard switch, then deletion. This ticket must not grow into a remote-SQLite adapter, a general parity layer, or an enterprise seat-migration platform.

Problem

The local wake final mile still owns server-side graph responsibilities. Docker-canonical Memory Core cannot be the graph authority while a host daemon independently tails and mutates the same graph.

We need the smallest graphless host edge that preserves local wake delivery, presence/no-clobber behavior, and turn-priced coalescing. Once witnessed on the real machine, the legacy Shape-C graph tail must be deleted.

Architectural reality

ADR 0002 already orders wake transport as Shape A → Shape B → Shape C and prefers Shape B when webhook delivery is available. Memory Core already contains subscription evaluation/coalescing and webhook-delivery building blocks, including HMAC signing, retries, and client-driven resync semantics. What is missing is the bounded same-machine receiver and the live route that feeds it.

The existing turn-priced Shape-C consumer also carries a rolling-window, refractory-period, and hard-cap amendment. Moving this resident to Shape B reopens that specific ADR contract; it cannot silently fall back to request-priced webhook coalescing.

neomjs/neo-agent-brain#129 is adjacent prior art for generic outbound wake streams, remote developer machines, and exclusive-seat migration. This ticket is intentionally not that product surface. It is a native child of neomjs/neo-agent-brain#84 for one same-host Docker cutover.

Intended solution

1. Complete live Shape-B evaluation and webhook delivery for active subscriptions inside container-owned Memory Core.
2. Add a small host receiver with an explicit Docker-reachable IP bind. It must verify the configured HMAC signature before durable acceptance; the live cutover witnesses the bind and restricts a broader-than-loopback port at the host firewall.
3. Persist accepted events before returning success, with 0600 host-local state and stable event/source identifiers. Before invoking a non-idempotent host adapter, durably transition the event from pending to dispatching; restart drains pending, while a stale dispatching item becomes terminal unknown and is never replayed. The mailbox remains authoritative for that ambiguity.
4. Extract the local-effect contracts needed after cutover. Graph-resident presence and wakePolicy stay in container Memory Core; the graphless receiver adapters enforce only facts available on the host: live process/session authority, exact instance targeting, focus safety, draft preservation, and the selected local invocation. They import no graph, SQLite, Memory Core query/config, or database path.
5. Preserve the turn-priced rolling window, refractory period, and hard cap for this route, and amend ADR 0002 to make that ownership explicit.
6. Keep restart semantics minimal: webhook retries cover bounded receiver outages; after retry exhaustion the mailbox remains authoritative. A fresh event after receiver restart must wake the seat, and previously unread messages surface in that turn. Do not add resident-PAT aggregation or a privileged all-seat resync credential merely to reconstruct an already-expired local invocation.
7. Switch neomjs/neo-agent-brain#84 to this receiver, witness real Docker Memory Core → real host-seat delivery, then delete the legacy Shape-C graph tail and its superseded tests.

Contract ledger

Acceptance criteria

• The host receiver has a static negative-import proof for better-sqlite3, graph services/queries, and graph/database paths.
• Missing or invalid signatures return a non-success response and cause no durable accept, cursor advance, or process dispatch.
• A valid event is durably persisted before 2xx; retrying the same stable event/source ID dispatches at most once.
• A crash after acceptance but before adapter invocation leaves durable pending work that restart drains. A crash during a non-idempotent adapter invocation leaves terminal unknown state that restart does not replay; mailbox unread state remains authoritative.
• Turn-priced rolling-window, refractory-period, and hard-cap behavior is covered at the new ownership boundary.
• Graph-resident presence state stays container-owned and is never copied into the host receiver; wrong/stale local targets and UI no-clobber failures fail closed; mailbox unread state remains authoritative.
• The implementation records the live cutover and restart witnesses as neomjs/neo-agent-brain#84 obligations without claiming them here.
• No shared GitHub PAT, all-seat token, remote SQL/graph adapter, generic lease/migration controller, or parallel topology is introduced.
• ADR 0002 records the turn-priced Shape-B coalescing and restart/degradation contract.

Cutover evidence owned by neomjs/neo-agent-brain#84

These remain mandatory for the hard cut but do not block merging this prerequisite implementation:

• A live same-machine witness proves Docker Memory Core → signed host receiver on the explicit host bind → real resident wake; loopback reachability is not assumed.
• A receiver restart followed by a fresh wake succeeds; previously unread messages appear in the resumed turn.
• neomjs/neo-agent-brain#84 consumes this edge and its cleanup removes the superseded Shape-C graph tail.

Decision impact

This is a bounded amendment to ADR 0002's wake-delivery shape and coalescing ownership. It aligns with ADR 0014's container authority and must follow ADR 0019 for every AiConfig read/default involved.

Out of scope

• Generic remote/NAT/multi-machine delivery and exclusive-seat migration (#14168)
• Fleet Manager or a permanent compatibility/parity layer
• The cutover/backup procedure itself (#16167)
• Memory Core or Knowledge Base transport migration beyond this wake route
• Global wake-attention policy changes

Avoided traps

• Mounting or proxying graph/SQLite back to the host
• Centralizing resident GitHub PATs or introducing an all-seat bypass credential
• Importing neomjs/neo-agent-brain#129's lease/migration scope into a one-machine prerequisite
• Building a host-side graph/presence mirror or permanent compatibility adapter; the receiver module is the post-cutover local-effect owner and neomjs/neo-agent-brain#84 deletes the superseded Shape-C copies after the witness
• Assuming a bridge-network container can reach a host listener bound to 127.0.0.1; the deployment uses an explicit witnessed bind and HMAC authority
• Claiming an expired offline invocation was delivered when only unread mailbox state persists

Related

• Parent/cutover: neomjs/neo-agent-brain#84
• Epic: neomjs/neo-agent-brain#90
• Adjacent general stream: neomjs/neo-agent-brain#129
• Wake transport/presence prior art: neomjs/neo#15800, neomjs/neo#16013, neomjs/neo#15677
• Source discussion: https://github.com/orgs/neomjs/discussions/15595
• ADRs: 0002, 0014, 0019
• Docker container-to-host route: https://docs.docker.com/desktop/features/networking/networking-how-tos/#connect-a-container-to-a-service-on-the-host

Freshness and duplicate sweep

Immediately before filing, the latest 20 open issues by creation time, the current A2A mailbox, and a Knowledge Base ticket search for graphless Shape B host dispatcher local Docker wake delivery SQLite were checked. No issue owns this same-host, graphless hard-cut prerequisite; neomjs/neo-agent-brain#129 is related but materially broader.

Origin

• Session: 71ff2f5e-17d6-47b2-90db-82bc1773b0a0
• Retrieval hint: Shape B signed host dispatcher graphless local Docker wake neomjs/neo-agent-brain#84