Wake substrate evolution: 3-signal model + Shape B heartbeat pulse

Context

Graduated from Discussion #11992 (Ideation Sandbox) after a 3-cycle convergence:

• Cycle-1: initial proposal (4-signal model + Shape A-first heartbeat-via-MailboxService).
• Cycle-2: @neo-gpt [GRADUATION_DEFERRED] with §5.2 sweep findings (Shape A mailbox-UX blocker, fresh signal falsification via live subscription V-B-A, backoff state location guidance).
• Cycle-3: @tobiu depth-floor pushback on the "Shape A as diagnostic fallback" hedge → Shape A dropped entirely, fresh signal dropped (redundant once active includes received-side activity), 3-signal model. @neo-gpt re-signal [GRADUATION_APPROVED] at cycle-3 body.

Quorum reached (§6.2 Tier-1):

• [AUTHOR_SIGNAL by @neo-opus-ada] @ Discussion #11992 cycle-3 body 2026-05-25T20:50:21Z
• [GRADUATION_APPROVED by @neo-gpt] @ Discussion #11992 discussioncomment-17054029 2026-05-25T20:53:02Z
• 2 active families with signal ✓ + 1 non-author family APPROVED ✓
• Google family operator_benched (archived in ## Unresolved Liveness below)

Origin Session ID: 8f1a91ee-3ee4-4e4b-9865-b5810f6be353

The Problem

The current wake substrate has 4 documented failure modes that the 3-cycle Discussion exposed:

1. Codex Desktop wake gap: SwarmHeartbeatService.tmuxInjectPulsePrompt() (line 657) delivers pulses via tmux send-keys — silently no-ops on non-tmux harnesses. Codex Desktop is native macOS, no tmux. Dead path.
2. Structurally-blocked harness restart-loops: the cadence layer has no model of harness readiness. Rate-limited (vendor weekly limits), operator-benched, or crash-loop-broken harnesses get banged on every 15m, producing rejection responses or zombie processes.
3. Substrate-boundary violation in any fix that touches MC: the rejected PR #11982 attempted to put a codexEligibleByTargetConfig projection in HealthService.mjs — operator rejected because wake substrate is Orchestrator-owned, not MC-owned. The fix must live in the Orchestrator + bridge-daemon + WakeSubscriptionService surface, not in MC observability surfaces.
4. Marathon-session + context-compaction substrate-invisibility: Neo agent sessions run 10h+ with multiple context-compactions inside a single MC session. Context compactions are agent-internal — orchestrator and bridge-daemon see no signal. Any substrate that depends on session-boundary state (subscription updatedAt, boot markers, harness PID changes) is broken for the common case. Only activity-derived signals (A2A graph) are durable across how Neo agents actually run.

The Architectural Reality

• WakeSubscriptionService (ai/services/memory-core/WakeSubscriptionService.mjs): owns subscription state (Shape A: mcp-notifications, Shape B: a2a-webhook, Shape C: bridge-daemon) + trigger evaluation. Per ADR 0002 §6.1.6, resync-based — consumers poll resync({sinceLogId}). Cycle-3 graduation requires extending §6.1.6 with a new ephemeral-GraphLog-entry semantic for heartbeat pulses (Shape B).
• MailboxService (ai/services/memory-core/MailboxService.mjs): persists MESSAGE nodes via addMessage (lines 337, 548); creates SENT_TO edges that trigger SENT_TO_ME subscription evaluator unless wakeSuppressed: true. Cycle-3 rejection of Shape A: heartbeat-via-MailboxService creates durable mailbox spam (~96 msgs/day/identity) + transcript-injected wake-blocks via bridge-daemon :522-538. Unacceptable Codex Desktop mailbox UX per @neo-gpt cycle-2 empirical authority.
• SwarmHeartbeatService (ai/daemons/orchestrator/services/SwarmHeartbeatService.mjs): owns the cadence + per-pulse activities (TTL sweep, sunset detection, idle-out nudge, tmux-inject). The tmux-inject step is the immediate Codex-wake-gap defect; the activity-detection + readiness-modeling gap is the deeper architectural concern.
• Bridge daemon (ai/daemons/bridge/daemon.mjs): owns harness-target wake delivery (osascript / codex-app-server / antigravity-cli / claude-cli adapters). Reads active WAKE_SUBSCRIPTION rows; dispatches when triggered. Cycle-3 architectural decision: bridge-daemon is the canonical wake-delivery layer (single source of truth); all other services consume wake events that the bridge-daemon dispatches.
• idleOutNudge.mjs (ai/scripts/lifecycle/idleOutNudge.mjs:7): currently uses MailboxService.addMessage for heartbeat — the Shape A path. Refactored cycle-3 cleanup: calls WakeSubscriptionService.emitHeartbeatPulse instead.
• TaskStateService + Orchestrator.stateFile + trioWakeCooldown (Orchestrator.mjs:439-453, TaskStateService.mjs:96-124, trioWakeCooldown.mjs:20-92): pre-existing primitives for orchestrator-local persisted state. Cycle-3 OQ3 resolution: backoff state for the ready signal lives in orchestrator-local persisted file (either orchestrator-state.json per-task block OR sibling .neo-ai-data/wake-daemon/backoff.json), not on WAKE_SUBSCRIPTION properties, not a new graph node type.

The Fix — 3-Signal Wake Model + Shape B Implementation

Wake = active AND idle AND ready.

Wake Delivery: all wakes flow through the bridge-daemon's existing harness-adapter set (osascript / codex-app-server / antigravity-cli / claude-cli). Heartbeat pulses use WakeSubscriptionService.emitHeartbeatPulse({targetIdentity}) — a new method that creates an ephemeral GraphLog entry (no MESSAGE node persisted, no SENT_TO edge that would surface in listMessages() inbox views). Bridge-daemon's existing resync() polling picks it up via a new trigger semantic (or discriminated subtype on existing eval).

Decomposition into 3 sub-tickets (per cycle-3 §5.2 sweep #6 + Graduation Criteria #6):

• Sub-i: Shape B emitHeartbeatPulse mechanism + ADR 0002 §6.1.6 update for ephemeral-GraphLog-entry semantic
• Sub-ii: 3-signal derivation (active/idle/ready) + orchestrator-local persisted backoff state + readiness-sentinel parser with structured task-envelope authority
• Sub-iii: tmux-inject + Shape A heartbeat-mailbox-path removal cleanup (refactor idleOutNudge.mjs to call emitHeartbeatPulse)

Contract Ledger

Decision Record Impact

amends ADR 0002 §6.1.6 — extends the resync-based wake-event contract with a new ephemeral-GraphLog-entry semantic for heartbeat pulses. No conflict with the existing accepted ADR direction; this is an additive extension to handle the heartbeat-pulse case without forcing MESSAGE-node persistence. ADR successor-risk audit per ticket-intake/references/adr-successor-risk-audit.md: the extension is backward-compatible (existing SENT_TO_ME / TASK_STATE_CHANGED / PERMISSION_GRANTED triggers + their resync semantics unchanged); old consumers continue to function; new consumers can opt in to the heartbeat-pulse trigger.

Acceptance Criteria

Epic-level ACs (gating Epic-close)

• AC1 — All 3 sub-tickets land + cross-family review per pull-request §6.1 on each
• AC2 — WakeSubscriptionService.emitHeartbeatPulse({targetIdentity}) ships with explicit tests proving heartbeat pulses do not create MESSAGE nodes, SENT_TO edges, inbox rows, or wake-visible mailbox artifacts (per @neo-gpt cycle-3 residual #1)
• AC3 — ADR 0002 §6.1.6 updated in Sub-i to document the ephemeral GraphLog wake semantic (per @neo-gpt cycle-3 residual #2)
• AC4 — Orchestrator-local backoff state implementation includes restart-persistence, corrupt-state fallback, TTL expiry, and per-identity isolation tests (per @neo-gpt cycle-3 residual #3)
• AC5 — Readiness-sentinel parser validates structured task/envelope fields and rejects subject-only spoofing (per @neo-gpt cycle-3 residual #4)
• AC6 — Cleanup sub removes both legacy tmux injection and the Shape A heartbeat-mailbox path entirely — not merely bypasses them (per @neo-gpt cycle-3 residual #5). Post-merge: grep -rn "tmuxInjectPulsePrompt" ai/ test/ returns zero matches; idleOutNudge.mjs no longer references MailboxService.addMessage
• AC7 — Wake substrate runbook (learn/agentos/wake-substrate/PersistentProcessManagement.md + NightShiftLeasedDriver.md) updated to document the 3-signal model + Shape B canonical wake-pulse path
• AC8 — Post-merge operator confirmation: Codex Desktop wakes from orchestrator heartbeat cadence when active AND idle AND ready (the original symptom #11872 was reframed-and-rejected for)

Sub-i ACs (Shape B emitHeartbeatPulse + ADR update)

• Sub-i.1 — WakeSubscriptionService.emitHeartbeatPulse({targetIdentity}) implemented; creates ephemeral GraphLog entry tagged as heartbeat-pulse; no MESSAGE/SENT_TO/inbox artifact (test-verified)
• Sub-i.2 — Bridge-daemon's resync() picks up heartbeat-pulse entries via new trigger semantic or discriminated subtype on existing eval
• Sub-i.3 — ADR 0002 §6.1.6 updated with ephemeral-GraphLog-entry semantic documentation
• Sub-i.4 — Unit tests cover: no-MESSAGE assertion, no-SENT_TO assertion, no-inbox-surface assertion, bridge-daemon resync consumption assertion
• Sub-i.5 — Cross-family review per pull-request §6.1

Sub-ii ACs (3-signal derivation + backoff + readiness sentinel)

• Sub-ii.1 — 3-signal derivation pure function: (identity, current-time, A2A-graph-state, readiness-sentinel-state, orchestrator-state-backoff) → wake-decision
• Sub-ii.2 — Orchestrator-local backoff state in orchestrator-state.json per-task block OR sibling .neo-ai-data/wake-daemon/backoff.json (decide per V-B-A of restart-resilience + corruptibility)
• Sub-ii.3 — Backoff state tests: restart-persistence, corrupt-state graceful fallback, TTL expiry, per-identity isolation
• Sub-ii.4 — Readiness-sentinel parser reads structured task envelope ({type: 'wake-readiness', ready, reason, expiresAt}); subject-only spoofing rejected; operator/self most-restrictive-wins on expiresAt
• Sub-ii.5 — Unit tests cover all 4 known pathological cases (drop-active wakes departed; drop-idle interrupts work; drop-ready loops on blocked; operator manual-prompt grace)
• Sub-ii.6 — Cross-family review per pull-request §6.1

Sub-iii ACs (tmux + Shape A cleanup)

• Sub-iii.1 — SwarmHeartbeatService.tmuxInjectPulsePrompt() method deleted entirely
• Sub-iii.2 — SwarmHeartbeatService.pulse() Step 7 replaced with emitHeartbeatPulse per-target iteration (driven by 3-signal decision from Sub-ii)
• Sub-iii.3 — idleOutNudge.mjs refactored to call WakeSubscriptionService.emitHeartbeatPulse instead of MailboxService.addMessage; verified no MESSAGE node created
• Sub-iii.4 — Wake substrate runbook updated (PersistentProcessManagement.md + NightShiftLeasedDriver.md)
• Sub-iii.5 — Post-merge greps: grep -rn "tmuxInjectPulsePrompt|tmux.*pulse" ai/ test/ returns zero; idleOutNudge.mjs does not reference MailboxService.addMessage
• Sub-iii.6 — Cross-family review per pull-request §6.1

Out of Scope

• Substantial rewrite of WakeSubscriptionService to push-based (drop resync polling). Discussion #11992 cycle-3 explicitly deferred this — the 3-signal model is orthogonal to resync-vs-push, and resync is not empirically motivated to change.
• Bridge-daemon Codex adapter debugging (OQ6). Spun out as sibling concern; needs live bridge-daemon log capture during heartbeat dispatch attempt to @neo-gpt. Tomorrow's client work is the natural empirical anchor — separate ticket will be filed when the trace is captured.
• MC HealthService wake observability surface. Explicitly rejected via PR #11982 closure today; substrate-boundary violation memory anchor in feedback_substrate_boundary_review_floor.md.
• New MCP tool for wake-readiness reporting. Operator constraint: MCP tool cap ~100, recommended ≤50, currently 4 main servers >100. No new tools.

Avoided Traps / Gold Standards Rejected

• ❌ "Shape A as diagnostic fallback" — explicitly rejected cycle-3 per @tobiu pushback. Preserving Shape A is the same preserve-the-workaround instinct that motivated rejected #11872 / #11982. If Shape B is substrate-correct, Shape A is just legacy.
• ❌ fresh signal via WAKE_SUBSCRIPTION.updatedAt — explicitly rejected cycle-3. Falsified by @neo-gpt cycle-2 live V-B-A; rendered moot cycle-3 by collapsing to 3-signal model where received-activity in active window handles the manual-prompt edge case naturally.
• ❌ Per-identity boot-marker primitive — rejected as solving a rare edge case that doesn't exist in the marathon-session common case (compactions are invisible to orchestrator; "boot" is rare).
• ❌ codexEligibleByTargetConfig in MC HealthService — rejected via PR #11982 closure; substrate-boundary violation.
• ❌ Hardcoded Neo-internal identities in dispatch logic — captured in feedback_no_neo_internal_identity_leakage_in_client_deployed_code.md.

Related

• Graduation Discussion: Discussion #11992 — Wake substrate evolution (3-cycle convergence, signal-ledger archived below)
• Rejected predecessors: #11872 (closed not planned — "workaround" framing rejected), PR #11982 (closed — substrate-boundary violation)
• Wake substrate primitives reused: #10671 (wake delivery), #11766 (orchestrator-owned swarm heartbeat lane), #11797 (controlled @neo-gpt SENT_TO_ME bridge delivery validation), #11804 (identity normalization)
• Memory anchors from today's session: feedback_substrate_boundary_review_floor.md, feedback_no_neo_internal_identity_leakage_in_client_deployed_code.md, feedback_neo_class_module_level_functions_anti_pattern.md

Signal Ledger

Unresolved Dissent

Unresolved Liveness

Discussion Criteria Mapping

Handoff Retrieval Hints

• Semantic: query_raw_memories({query: "wake substrate 3-signal model emitHeartbeatPulse Shape B bridge-daemon"})
• Empirical: git log --all --oneline --grep="#11990\|#11992\|wake substrate"
• Discussion archaeology (post-graduation, closed-as-RESOLVED): https://github.com/orgs/neomjs/discussions/11992