What is the 'Neural Link'?

The Neural Link is a bi-directional bridge that connects AI agents (like Gemini or Claude) directly to the Neo.mjs runtime. It allows agents to 'see' the application's Scene Graph, inspect component state, verify event listeners, and even mutate the running application in real-time. This turns the application into a 'glass box' for AI, enabling autonomous debugging and feature development.

Why is Neo.mjs called an 'Application Engine' instead of a framework?

Traditional frameworks are general-purpose libraries (like a Toyota) that help you organize code, but they compile away into ephemeral DOM nodes. Neo.mjs is a precision-engineered runtime (like an F1 car), similar to Unreal Engine for games. It maintains a persistent 'Scene Graph' of objects in a separate worker thread. These objects retain their identity, state, and relationships, allowing for advanced capabilities like multi-window orchestration, runtime permutation, and deep AI introspection that are impossible with 'melted plastic' DOM-based frameworks.

What is 'Context Engineering'?

Context Engineering is the practice of curating the environment and information flow for AI agents to maximize their autonomy. In Neo.mjs, this is implemented via three Model Context Protocol (MCP) servers: a Knowledge Base for semantic code understanding, a Memory Core for learning from past sessions, and a GitHub Workflow server for project management. This ecosystem allows agents to work as fully integrated members of the development team.

What is 'Object Permanence' in the context of Neo.mjs?

In Neo.mjs, UI components are persistent JavaScript objects living in the App Worker, not just transient rendering results. This 'Object Permanence' means a component (like a Dashboard) maintains its state (scroll position, user input, internal logic) even if it is detached from the DOM or moved to a different browser window. This is the 'Lego Technic' approach versus the 'Duplo' approach of traditional frameworks.

What is an 'Agent Operating System'?

Neo.mjs v11 introduced the concept of an Agent OS, where the platform itself provides the tools and interfaces for AI agents to operate. It combines a standalone, type-safe AI SDK for autonomous 'Code Execution' with the Neural Link for runtime control. This enables agents to monitor, debug, and heal the application autonomously, effectively acting as an operating system for synthetic intelligence.

How does Neo.mjs handle multi-window applications?

Neo.mjs uses shared web workers to run a single application instance across multiple browser windows. All windows share the same application state and data in real-time. Components can even move between windows while retaining their JavaScript instances. This enables desktop-class experiences like multi-window IDEs, browser-based email clients, and multi-screen control rooms.

What makes Neo.mjs different from React, Angular, or Vue?

Neo.mjs is fundamentally different in its architecture: (1) It uses True Multithreading via web workers to prevent UI jank, (2) It is an AI-Native Application Engine with built-in bridges for AI collaboration, and (3) It treats components as persistent objects in a Scene Graph, enabling native multi-window support and runtime permutation.

Frontmatter

id	11797
title	Validate orchestrator swarm-heartbeat wake delivery
state	Closed
labels	bugaitestingregressionarchitecture
assignees	neo-gpt
createdAt	May 23, 2026, 1:20 AM
updatedAt	May 23, 2026, 3:35 AM
githubUrl	https://github.com/neomjs/neo/issues/11797
author	neo-gpt
commentsCount	3
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	May 23, 2026, 3:35 AM

Validate orchestrator swarm-heartbeat wake delivery

Name: Neo.mjs Application Engine
Author: Neo.mjs

Closedbugaitestingregressionarchitecture

neo-gpt commented on May 23, 2026, 1:20 AM

Context

Operator observation on 2026-05-23 after PR #11772 merged: dev was pulled and the Orchestrator was restarted, but no wakeup messages have been observed for @neo-opus-4-7 or @neo-gpt.

This directly targets the post-merge validation residual from PR #11772 / issue #11766. PR #11772 folded the standalone swarm-heartbeat daemon into the Orchestrator as a local-only scheduled lane and explicitly left L4 runtime validation open:

local maintainer checkout: confirm a running Orchestrator drives heartbeat pulses (.neo-ai-data/wake-daemon/heartbeat.alive mtime advancing; heartbeat log/activity);
cloud profile: confirm the lane stays off.

The operator now supplied negative runtime evidence for the local profile: after restart, no visible wake delivery has happened.

The Problem

The merge replaced the old standalone heartbeat process with an Orchestrator-owned lane. Unit coverage verified the shape, but the live end-to-end path is still unproven and may be silently failing.

The dangerous failure mode is not just "no wake". It is false confidence: the Orchestrator can be running, and individual unit tests can pass, while the folded heartbeat lane either never becomes due, never emits, exits early, hits the wake-safety gate, or sends output to the wrong/obsolete harness surface.

Architectural Reality

Verified surfaces:

PR #11772 merged at 2026-05-22T17:28:26Z and resolves #11766.
ai/daemons/Orchestrator.mjs initializes the heartbeat lane when swarmHeartbeatEnabled is true, then drives SWARM_HEARTBEAT_TASK_NAME through cadenceEngine.runIfDue and records task outcomes.
ai/scripts/orchestrator-daemon.mjs resolves NEO_ORCHESTRATOR_SWARM_HEARTBEAT_INTERVAL_MS and NEO_ORCHESTRATOR_SWARM_HEARTBEAT_ENABLED from env/config.
ai/daemons/SwarmHeartbeatService.mjs#pulse() touches heartbeat.alive, checks locks, sweeps expired tasks, runs sunset / idle-out / all-agent-idle checks, then bypasses push-capable identities before the old token-economy tmux pulse path.

Important implication: an operator-visible wake can fail for several distinct reasons. The verification must isolate which stage is failing, not just assert "heartbeat broken".

Duplicate Sweep

KB ticket search surfaced #10396 / #10399 / #10312 as older generic heartbeat / swarm-stall substrate tickets, and #10931 as a stale-threshold observability bug. None is the post-#11772 folded-Orchestrator live validation gap.
GitHub search for open SwarmHeartbeatService / Orchestrator / wake issues surfaced #11075, which is config constants cleanup and not a live wake-delivery verification issue.
#11766 is the source implementation ticket and is closed; its L4 post-merge validation residual needs this follow-up ticket because the operator now reports negative runtime evidence.

The Fix

Build a focused verification + diagnosis pass for the folded heartbeat lane:

Confirm the Orchestrator actually schedules swarm-heartbeat after restart.
Confirm .neo-ai-data/wake-daemon/heartbeat.alive advances on each due pulse.
Confirm TaskStateService / HealthService exposes heartbeat task outcomes (running, completed, failed, lastReason) for the folded lane.
Force a short-interval local run using NEO_ORCHESTRATOR_SWARM_HEARTBEAT_INTERVAL_MS and explicit NEO_ORCHESTRATOR_SWARM_HEARTBEAT_ENABLED=true, then capture whether the lane reaches each pulse() branch.
Validate actual wake delivery to the intended active harness identities (@neo-opus-4-7, @neo-gpt) or prove why delivery is correctly skipped.
Add the smallest durable diagnostic or test/runbook needed so future agents can verify this without relying on operator observation alone.

Acceptance Criteria

AC1 — Local-profile Orchestrator run proves swarm-heartbeat is enabled, due, and invoked after restart.
AC2 — heartbeat.alive mtime advancement is measured across at least two due pulses.
AC3 — Orchestrator task outcome state for swarm-heartbeat is inspected and records success/failure reason rather than staying silent.
AC4 — Wake-safety gate state, concurrency-lock state, push-capable bypass, all-agent-idle result, sunset result, and token-economy gate are each checked or logged for the failing run.
AC5 — At least one controlled wake-delivery path is proven end-to-end for an intended active harness identity, OR a concrete blocker is identified and converted into a narrow follow-up bug.
AC6 — Cloud-profile negative assertion remains true: NEO_AI_DEPLOYMENT_MODE=cloud leaves the local-only heartbeat lane off by default.
AC7 — Add or update focused regression coverage / diagnostic runbook so the folded-lane post-merge validation can be repeated without guesswork.

Out of Scope

Rewriting the heartbeat architecture again before the live failure stage is isolated.
Reopening the retired standalone swarm-heartbeat.sh / launchd path as the primary fix.
Changing unrelated Orchestrator heavy-maintenance lanes (KB sync, dream, golden path, backup).
Solving #11075 config-constant cleanup.

Avoided Traps

Trap	Why rejected
Treating "Orchestrator process is running" as proof	The folded heartbeat lane can be disabled, not due, early-returning, or failing after Orchestrator start.
Treating absence of visible wake as one bug	The pulse pipeline has multiple intentional skips and safety gates; diagnostics must name the exact stage.
Reverting to the old daemon path immediately	#11766 deliberately retired that tech debt. The first step is to validate the folded lane and identify any narrow regression.
Only checking Chroma / KB health	This is a local wake-substrate pipeline; Chroma health can be unrelated to whether heartbeat delivery reaches harnesses.

#11766 — source issue, closed by PR #11772.
PR #11772 — folded swarm-heartbeat into the Orchestrator and left L4 post-merge validation open.
#11730 — v13 post-MVP residual workstreams parent.
#10601 / #10399 — older auto-wakeup / swarm-stall substrate history.
#10931 — prior wake liveness observability threshold issue; adjacent but not duplicate.

Origin Session ID: d60db68f-8ff0-48a6-b168-237ca9dca2a0

Handoff Retrieval Hint: query_raw_memories("orchestrator swarm-heartbeat folded lane no wake after restart #11772 #11766")

tobiu referenced in commit f566c0a - "fix(ai): normalize swarm heartbeat identity (#11797) (#11804) on May 23, 2026, 2:35 AM