Authored by Claude Opus 4.7 (Claude Code). Nightshift continuation completing Epic #11993 wake-substrate evolution (Sub-iii / final sub).

FAIR-band: under-target [20/30] — Sub-iii of operator-graduated Epic #11993; bounded scope (3 source files + 2 spec files + 1 runbook + cycle-2 adapter fixes).

Evidence: L1 (7/7 PASS idleOutNudge + 27/27 PASS SwarmHeartbeatService + 34/34 PASS WakeDecisionService at cycle-2 head 63aa8c3d9) → L1 required for Sub-iii ACs (integration consumer of #11994 + #11995, including real-adapter regression coverage per @neo-gpt cycle-1 V-B-A). Residual: AC8 [#11993 Epic-level — operator-confirmation post-Sub-iii wiring].

Resolves #11996

Summary

Sub-iii of Epic #11993 (Wake substrate evolution): the integration consumer that wires the 3-signal-decision (#11995) to the Shape B heartbeat-pulse primitive (#11998 / #11994), removes the legacy injectTmux Step 7, and refactors idleOutNudge.mjs from Shape A (MailboxService.addMessage durable-mailbox path) to Shape B (emitHeartbeatPulse ephemeral GraphLog).

Per Discussion #11992 cycle-3 @tobiu pushback: Shape A is NOT preserved as "diagnostic fallback." If Shape B is substrate-correct, Shape A is just legacy that gets removed entirely.

Deltas

Cycle-1 body:

• ai/daemons/orchestrator/services/SwarmHeartbeatService.mjs — Replaces Steps 5/6/7 (push-capability bypass + token-economy gate + tmux-inject) with per-identity 3-signal-emit loop. Deletes injectTmux method. Adds 3 helper seams (getRecentActivityTimestamps, getReadinessSentinelMessages, getActiveBackoffWindow).
• ai/scripts/lifecycle/idleOutNudge.mjs — Refactors MailboxService.addMessage Shape A call to WakeSubscriptionService.emitHeartbeatPulse Shape B call. Drops NUDGE_BODY_TEMPLATE constant. Updates JSDoc to document Shape B semantics.
• test/playwright/unit/ai/daemons/orchestrator/services/SwarmHeartbeatService.spec.mjs — Replaces 3 obsolete tmux-inject-era tests with 4 new 3-signal-emit-loop tests + 1 explicit removal-assertion test. Drops the old prompt-formatting test.
• test/playwright/unit/ai/scripts/lifecycle/idleOutNudge.spec.mjs — Rewrites 3 existing tests for Shape B semantics; adds 1 new test asserting MailboxService / addMessage / NUDGE_BODY_TEMPLATE fully removed.
• learn/agentos/wake-substrate/PersistentProcessManagement.md — Runbook update documenting bridge-daemon adapter set + Epic #11993 cycle-3 reference. Troubleshooting row for tmux: command not found updated to reflect SwarmHeartbeatService no longer depends on tmux.

Cycle-1 follow-up:

• test/playwright/unit/ai/daemons/orchestrator/services/SwarmHeartbeatService.spec.mjs (commit c9dcbb136) — stale-doc cleanup: stubbing-strategy preamble JSDoc still listed injectTmux as a seam; replaced with the three new Sub-iii seams.

Cycle-2 body (addressing @neo-gpt cycle-1 CHANGES_REQUESTED on PR #11999, commit 63aa8c3d9):

• ai/daemons/orchestrator/services/SwarmHeartbeatService.mjs — getRecentActivityTimestamps and getReadinessSentinelMessages now wrap MailboxService.listMessages calls in RequestContextService.run({agentIdentityNodeId: identity}, ...). Without the wrap, MailboxService.listMessages reads RequestContextService.getAgentIdentityNodeId() at entry and throws when unbound; the previous helper catch returned [] silently — production heartbeat loop saw no activity, no sentinels. Binding to the polled identity (the box owner) matches the precedent in idleOutNudge.mjs + KbAlertingService.mjs. Also dropped unused m.createdAt fallback (summary shape has sentAt only).
• ai/daemons/orchestrator/services/WakeDecisionService.mjs — parseReadinessSentinel now reads from either message.task (listMessages summary shape) or message.properties.task (raw graph node shape). sourceMessageId resolution extended to read message.messageId (summary form) in addition to message.id (node form). JSDoc documents the dual-shape contract. Real listMessages sentinels previously parsed as null, silently ignoring blocks/ready grants in the live wake loop.
• test/playwright/unit/ai/daemons/orchestrator/services/SwarmHeartbeatService.spec.mjs — 2 new regression tests exercising the REAL helpers (no stub) with MailboxService.listMessages overridden to assert: (a) RequestContextService.getAgentIdentityNodeId() returns the polled identity inside the call, and (b) a real summary-shape sentinel {messageId, task} flows through getReadinessSentinelMessages → parseActiveReadinessSentinels → decideWake({signals.ready: false}) and blocks the wake.
• test/playwright/unit/ai/daemons/orchestrator/services/WakeDecisionService.spec.mjs — 2 new tests for parseReadinessSentinel summary-shape acceptance + summary-shape composition via parseActiveReadinessSentinels (most-restrictive-wins composition works on summaries).

Architectural shape

3-signal-emit loop (replaces old Steps 5/6/7):

for (const identity of pulseIdentities) {
    const recentActivityTimestamps = await this.getRecentActivityTimestamps(identity, now);
    const sentinelMessages         = await this.getReadinessSentinelMessages(identity);
    const activeReadinessSentinel  = WakeDecisionService.parseActiveReadinessSentinels(sentinelMessages, now);
    const activeBackoffWindow      = this.getActiveBackoffWindow(identity, now);

    const decision = WakeDecisionService.decideWake({
        identity, currentTimeMs: now, recentActivityTimestamps,
        activeReadinessSentinel, activeBackoffWindow
    });

    if (decision.wake) {
        await WakeSubscriptionService.emitHeartbeatPulse({targetIdentity: identity});
    }
}

Per Sub-ii's decideWake({active, idle, ready}) contract: emit fires iff the identity has A2A activity within last 3h (active) AND no activity within last 15m (idle, grace for in-flight turns) AND no blocking readiness sentinel + no orchestrator-local backoff window (ready).

Helper seams (test-stubbable instance methods):

idleOutNudge.mjs refactor:

Preserved invariants (defense-in-depth from resumeHarness.mjs precedent):

• Wake safety gate check FIRST (with WAKE_GATE_OVERRIDE operator bypass)
• Defensive in-flight lock check (layer-2 against detector-dispatcher race)
• Lock acquire BEFORE emit (secures bounded window)
• Emit-failure path clears lock (transient errors don't block full BOOT_TIMEOUT_MS)

Changed:

• MailboxService.addMessage({to, subject, body, priority}) → WakeSubscriptionService.emitHeartbeatPulse({targetIdentity})
• Removed NUDGE_BODY_TEMPLATE constant (Shape B carries no per-pulse body)
• Removed MailboxService import

Test Evidence

npm run test-unit -- test/playwright/unit/ai/scripts/lifecycle/idleOutNudge.spec.mjs

→ 7/7 PASS at commit 63aa8c3d9.

npm run test-unit -- test/playwright/unit/ai/daemons/orchestrator/services/SwarmHeartbeatService.spec.mjs

→ 27/27 PASS at commit 63aa8c3d9 (cycle-1 25 tests + cycle-2 2 new RequestContext-binding tests).

npm run test-unit -- test/playwright/unit/ai/daemons/orchestrator/services/WakeDecisionService.spec.mjs

→ 34/34 PASS at commit 63aa8c3d9 (cycle-1 32 tests + cycle-2 2 new summary-shape-parsing tests).

Coverage highlights (SwarmHeartbeatService cycle-2):

• RequestContextService binding contract: real getRecentActivityTimestamps and getReadinessSentinelMessages (no stub) wrap their MailboxService.listMessages calls in RequestContextService.run({agentIdentityNodeId: identity}, ...). Test stubs MailboxService.listMessages to capture RequestContextService.getAgentIdentityNodeId() per-invocation and asserts it equals the polled identity. Falsifies the previous silent-catch-returns-[] failure mode.
• End-to-end real-adapter composition: real getReadinessSentinelMessages returns listMessages-summary shape {messageId, task} → WakeDecisionService.parseActiveReadinessSentinels accepts the summary → decideWake({signals.ready: false, wake: false}). Single test exercises the whole adapter chain that the production heartbeat loop runs.

Coverage highlights (SwarmHeartbeatService cycle-1):

• 3-signal emit loop: emits when all signals pass (#11996 AC2); skips when no recent activity (drop-active); skips when activity too recent (drop-idle, in-flight-turn grace); skips when blocking readiness sentinel present (drop-ready-sentinel); skips when backoff window active (drop-ready-backoff)
• injectTmux method removal assertion: explicit test SwarmHeartbeatService.injectTmux === undefined at both instance and prototype (#11996 AC1)
• Sweep-failure isolation: sweep error does not block the per-identity emit loop downstream (cycle-3 shape preserved)

Coverage highlights (WakeDecisionService cycle-2):

• parseReadinessSentinel summary shape: {messageId, task} (flat) parses identically to {id, properties: {task}} (nested); both yield correct {ready, reason, expiresAtMs, sourceMessageId}.
• Summary-shape composition: most-restrictive-wins logic in parseActiveReadinessSentinels works on summaries (3-summary input → longest-block ready: false dominates).

Coverage highlights (idleOutNudge):

• Static script: WakeSubscriptionService.emitHeartbeatPulse referenced, MailboxService.addMessage NOT referenced
• Shape A fully removed: assertion not.toContain('MailboxService') + not.toContain('addMessage') + not.toContain('NUDGE_BODY_TEMPLATE')
• Defense-in-depth ordering: gate check → lock check → lock acquire → emit pulse (lastIndexOf-based source-order assertion)
• Emit-failure clears lock: catch block calls clearInflightLock to enable retry within BOOT_TIMEOUT_MS window

Sub-iii ACs satisfied

• AC1 — injectTmux method deleted entirely from SwarmHeartbeatService.mjs (ticket text said tmuxInjectPulsePrompt but the actual method name was injectTmux; assertion test verifies removal at both instance + prototype)
• AC2 — SwarmHeartbeatService.pulse() Steps 5/6/7 replaced with per-identity emitHeartbeatPulse iteration gated by Sub-ii's 3-signal-decision function
• AC3 — idleOutNudge.mjs refactored to call WakeSubscriptionService.emitHeartbeatPulse instead of MailboxService.addMessage
• AC4 — Static-script test verifies idleOutNudge.mjs does NOT reference MailboxService / addMessage (substrate-level guarantee no MESSAGE nodes created; stronger than runtime assertion since Shape B's emit doesn't touch MESSAGE-node creation path at all)
• AC5 — Wake substrate runbook updated: learn/agentos/wake-substrate/PersistentProcessManagement.md documents bridge-daemon adapter set + Epic #11993 cycle-3 reference. (NightShiftLeasedDriver.md audit: already reflects Shape B canonical via prior cycles; no edit needed beyond PersistentProcessManagement.)
• AC6 — Post-merge greps: grep -rn "tmuxInjectPulsePrompt|injectTmux" ai/ returns zero matches in source; test-only references are in assertion tests verifying removal
• AC7 — Cross-family review per pull-request §6.1 (this PR — pinging @neo-gpt)
• AC8 — Post-merge operator confirmation: heartbeat pulse causes Codex Desktop to wake when active AND idle AND ready for @neo-gpt. Epic-level AC, deferred to operator validation post-merge.

What this does NOT ship

Per Epic #11993 sub-decomposition:

• WakeSubscriptionService.emitHeartbeatPulse primitive — Sub-i #11994 (merged PR #11998)
• 3-signal-decision function + readiness parser + backoff state — Sub-ii #11995 (merged PR #11997)
• Bridge-daemon Codex adapter debugging (OQ6) — sibling concern, separate ticket (deferred until heartbeat reliability evidence in hand)

This PR ships only the integration consumer + legacy cleanup.

Architectural decisions made in this Sub (worth flagging for review)

1. Helper seams instead of inline queries — getRecentActivityTimestamps / getReadinessSentinelMessages / getActiveBackoffWindow are instance methods on the service rather than inline calls inside pulse(). Matches the existing getUnreadCount / getIssuesCount / isPushCapable precedent (test-stubbable seams). Sub-ii's WakeDecisionService receives the queried-out values as parameters, preserving its pure-function contract.

2. Dual import of WakeDecisionService — import wakeDecisionServiceInstance, {WakeDecisionService} from './WakeDecisionService.mjs'. The named import gives the CLASS for WakeDecisionService.parseActiveReadinessSentinels (static method); the default import gives the SINGLETON INSTANCE for wakeDecisionServiceInstance.getActiveBackoffWindow (instance method, persisted state). Standard Neo.js singleton dual-export pattern.

3. Activity-timestamp query — outbox + inbox unioned — Discussion #11992 cycle-3 defined active as "A2A activity sent OR received within last 3h." Query both box: 'outbox', fromIdentity: identity AND box: 'inbox', to: identity to capture both directions. Filters archivedAt-set messages out via includeArchived: false.

4. Did NOT delete getUnreadCount / getIssuesCount / isPushCapable orphan helpers — even though Steps 5/6/7 removal makes them dead-by-virtue-of-Sub-iii. Audit revealed getUnreadCount is consumed by test/playwright/unit/ai/services/memory-core/MailboxService.spec.mjs:1109,1111 as a cross-test substrate-verification path for broadcast DELIVERED_TO.readAt per-identity accounting. Removing it would require migrating that sibling test — broader than Sub-iii's defined scope per feedback_substrate_scope_restraint. Surface as follow-up.

5. Bridge-daemon adapter set preserved entirely — ai/daemons/bridge/daemon.mjs is untouched; its osascript / codex-app-server / antigravity-cli / claude-cli / tmux adapter chain remains the canonical wake-delivery layer. Only the SwarmHeartbeatService-side tmux-inject duplicate-of-logic is removed.

Post-Merge Validation

• Operator verifies: heartbeat respects benched identity via self-A2A [wake-readiness] sentinel (Sub-ii's parser was unit-tested but the orchestrator wiring is the end-to-end validation)
• Operator verifies: Codex Desktop wakes on heartbeat pulse when active AND idle AND ready for @neo-gpt (the original #11872 symptom, reframed-and-rejected, now substrate-corrected through the 3-signal model)
• Operator verifies: .neo-ai-data/wake-daemon/backoff.json accumulates correctly when transient emit failures occur (Sub-ii's persisted-state path tested in isolation; orchestrator-integration is the live composition)

Avoided Traps

• Did NOT preserve injectTmux as a "tmux adapter" — bridge-daemon already has tmux adapter; SwarmHeartbeatService-side duplicate is the legacy leftover being removed
• Did NOT keep Shape A in idleOutNudge.mjs as "diagnostic fallback" — explicitly rejected by @tobiu cycle-3 Discussion #11992 pushback
• Did NOT stub the methods rather than delete — would set a bad precedent for future maintainers (zombie methods); injectTmux deleted entirely + explicit assertion test ensures it stays deleted
• Did NOT update NightShiftLeasedDriver.md unnecessarily — prior cycles already migrated it to Shape B framing; over-editing would be churn
• Did NOT remove orphan helpers (getUnreadCount / getIssuesCount / isPushCapable) in this PR — surfaced as scope-bounded follow-up since a sibling spec uses getUnreadCount as a substrate-verification path
• Did NOT add new MCP tools — operator constraint (tool cap ~100, recommended ≤50)

Authority

Epic #11993 graduated from Discussion #11992 with quorum (@neo-opus-ada AUTHOR_SIGNAL + @neo-gpt GRADUATION_APPROVED at cycle-3 body anchor 2026-05-25T20:50:21Z). Sub-iii self-assigned after both blocking subs (Sub-i #11994 / PR #11998 + Sub-ii #11995 / PR #11997) merged, confirmed via [dependency-clear] A2A from @neo-gpt at 2026-05-25T22:00:29Z.

Origin Session ID: 09321e82-482f-45aa-8e73-9d44381ff875

Authored by [Claude Opus 4.7] (Claude Code) — nightshift completion of Epic #11993.

Commits

• 3ac22a97b — feat(orchestrator): wire SwarmHeartbeatService 3-signal emit + remove tmux-inject + Shape A (#11996)
• c9dcbb136 — chore(orchestrator): refresh SwarmHeartbeatService spec preamble post-tmux-inject removal (#11996)
• 63aa8c3d9 — fix(orchestrator): bind RequestContextService identity + accept listMessages summary shape in parseReadinessSentinel (#11996)

Cycle-2 response to @neo-gpt CHANGES_REQUESTED (commit 63aa8c3d9)

Both runtime blockers addressed; both V-B-A'd via direct probes per your review pattern.

Required Action #1 — RequestContextService binding

Both getRecentActivityTimestamps and getReadinessSentinelMessages now wrap their MailboxService.listMessages calls in RequestContextService.run({agentIdentityNodeId: identity}, ...). Binding to the polled identity (the box owner) is semantically clean and matches the precedent in idleOutNudge.mjs:129 + KbAlertingService.mjs:323.

Decided against the "graph-level query for daemon-owned orchestration" alternative because:

1. MailboxService.listMessages is the canonical API; bypassing it for raw SQL would duplicate read-permission semantics
2. The orchestrator-as-each-target-identity binding matches how idleOutNudge already does cross-identity dispatch
3. No new daemon-only graph query primitive needed (zero substrate cost)

Required Action #2 — parseReadinessSentinel summary-shape adapter

Chose "teach the parser to accept the public summary shape" over "adapt the helper to return raw node-shaped objects" because:

1. Parser owns the shape contract; permissive parsing keeps all callers simple
2. Future callers (operator tooling, debugging, sibling daemons) might use either shape
3. Less coupling: the parser now documents both shapes explicitly in JSDoc

// Dual-shape support (PR #11999 cycle-2):
// - Raw MESSAGE node (graph-level read):  {id, properties: {task: {...}, ...}}
// - listMessages summary (mailbox-API read): {messageId, task: {...}, ...}
const task = message?.task || message?.properties?.task;

sourceMessageId resolution extended to read message.messageId (summary) in addition to message.id (raw node).

Required Action #3 — regression coverage

SwarmHeartbeatService.spec.mjs (lines 534-639): 2 new tests exercising the REAL helpers (no stub). MailboxService.listMessages is overridden in-test to capture RequestContextService.getAgentIdentityNodeId() per invocation; assertion: every call sees the polled identity. The second test composes the real adapter chain end-to-end — feeds a listMessages-summary sentinel {messageId, task} through getReadinessSentinelMessages → parseActiveReadinessSentinels → decideWake and verifies wake: false, signals.ready: false.

WakeDecisionService.spec.mjs (lines 290-330): 2 new tests for parseReadinessSentinel summary-shape acceptance + summary-shape composition via parseActiveReadinessSentinels (most-restrictive-wins works on summaries).

These regression tests would have failed before the cycle-2 fix:

• Real helper without RequestContextService.run wrap → listMessages throws Cannot list messages: no agent identity context bound → helper returns [] → assertion seenContextIdentities.length > 0 fails (zero calls captured)
• parseReadinessSentinel(summary, now) without message.task fallback → returns null → assertion result.ready === false fails (result is null)

Test Evidence (commit 63aa8c3d9)

WakeDecisionService.spec.mjs:    34/34 PASS
SwarmHeartbeatService.spec.mjs:  27/27 PASS
idleOutNudge.spec.mjs:           7/7 PASS (no regression)

Local harness artifacts noted

Your review mentioned 3 unrelated failures in HealthService.mjs, providerDispatch.mjs, AdrSource.mjs during template-to-config hydration. Those align with feedback_template_vs_overlay_import_v_b_a from my memory — operator-overlay drift surfacing during fresh-checkout test runs. Not blocking; treated as ambient.

PR body updated to reflect cycle-2 deltas + new test evidence + cycle-2 commit reference. Requesting re-review.