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	10787
title	Add daemon-only entrypoint to swarm-heartbeat.sh (split heartbeat from agent-CLI launcher)
state	Closed
labels	bugenhancementaiarchitecture
assignees	[]
createdAt	May 5, 2026, 10:31 PM
updatedAt	May 5, 2026, 11:08 PM
githubUrl	https://github.com/neomjs/neo/issues/10787
author	neo-opus-4-7
commentsCount	1
parentIssue	10671
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	May 5, 2026, 11:08 PM

Add daemon-only entrypoint to swarm-heartbeat.sh (split heartbeat from agent-CLI launcher)

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

Closedbugenhancementaiarchitecture

neo-opus-4-7 commented on May 5, 2026, 10:31 PM

Context

Surfaced 2026-05-05 by @neo-gpt during architectural review of PR #10782 (persistent-process management for swarm-heartbeat). PR #10782 was reshaped because the plist template targeted swarm-heartbeat.sh directly — but the script is not a pure daemon. With no args, it sets AGENT_CMD="claude" and executes the Claude CLI as part of its wrapper loop.

Result: a launchd plist invoking bash swarm-heartbeat.sh would try to launch Claude CLI under launchd, not run a pure heartbeat daemon. Wrong-shape executable target.

The Problem

ai/scripts/swarm-heartbeat.sh is dual-purpose by current shape:

Heartbeat-pulse subprocess (heartbeat_pulse & at top) — the actual daemon-shape work: polls SQLite for unread messages, consults sunset detector, dispatches recovery via resumeHarness.mjs when warranted, consults wakeSafetyGate.mjs before high-authority actions
Wrapper loop — manages an agent-CLI subprocess (AGENT_CMD="claude" default with no args; the script's main loop runs the agent CLI, with the heartbeat as a backgrounded peer)

This makes the script convenient for a developer running it interactively (one command starts both the agent CLI and the heartbeat) but NOT suitable as a launchd daemon target — launchd would inherit the wrapper's AGENT_CMD execution and attempt to launch the agent CLI in a non-interactive launchd context.

The persistent-process management substrate (PR #10782 / #10781 lane) needs a daemon-only entrypoint that:

Runs only the heartbeat-pulse poll loop
Does NOT execute the agent-CLI wrapper
Is suitable for launchd / systemd / equivalent process-manager invocation

The Architectural Reality

ai/scripts/swarm-heartbeat.sh — current dual-purpose script (heartbeat + agent-CLI wrapper)
ai/scripts/heartbeat_pulse (subprocess inside the script) — the actual daemon-shape work
ai/scripts/checkSunsetted.mjs, resumeHarness.mjs, wakeSafetyGate.mjs, sweepExpiredTasks.mjs — consumers chain
bridge-daemon.mjs — the Shape C delivery daemon (separate scope; runs persistently as PID 22447); does NOT need this entrypoint since it has its own startup mechanism
ADR 0002 (learn/agentos/decisions/0002-phase3-wake-substrate-standards-alignment.md) — codifies the bridge-daemon-vs-swarm-heartbeat split as intentional
session-sunset-workflow.md line 11 — explicit current contract: swarm-heartbeat.sh → checkSunsetted.mjs → resumeHarness.mjs is the recovery chain
idleOutNudge.mjs — split-of-concerns reference: heartbeat detects, bridge delivers

The Fix

Two equivalent shapes per @neo-gpt's recommendation:

Option A (smallest delta): add explicit --daemon-only (or --no-agent-cli) mode flag to swarm-heartbeat.sh. When the flag is set, skip the agent-CLI wrapper logic and run ONLY the heartbeat-pulse + recovery-dispatch poll loop. Plist + operator-doc point at bash swarm-heartbeat.sh --daemon-only.

Option B (cleaner separation): extract heartbeat-pulse + recovery-dispatch logic into a new file ai/scripts/swarm-heartbeat-daemon.sh (or swarm-heartbeat-daemon.mjs for the Node-orchestrator variant). The original swarm-heartbeat.sh stays as the developer-convenience interactive wrapper; the new file is the daemon-only target.

Recommendation: Option B (cleaner separation) — explicit two-file shape removes the dual-purpose ambiguity at the substrate level. Option A keeps backward compatibility but the dual-purpose design is the root of this issue; making it explicit-via-naming is the more durable fix. Sibling files (checkSunsetted.mjs, resumeHarness.mjs, etc.) are already separate-purpose; adding swarm-heartbeat-daemon.sh as a sibling matches the pattern.

If Option B is taken: the daemon entrypoint can also use a Node orchestrator (.mjs) instead of bash — gains type-safety + cross-platform parity — but that's scope-extension; v1 can match the existing bash style for minimal-delta.

Acceptance Criteria

(AC1) New daemon-only entrypoint exists (per Option A --daemon-only flag OR Option B separate file)
(AC2) Daemon-only entrypoint runs heartbeat-pulse + recovery-dispatch poll loop without launching the agent CLI
(AC3) Existing developer-convenience interactive shape (bash swarm-heartbeat.sh) preserved unchanged for backward compatibility
(AC4) Unit tests cover the daemon-only path: poll loop fires correctly without agent-CLI side effects
(AC5) Plist template (PR #10782) updated to point at the new entrypoint
(AC6) Operator-doc (PersistentProcessManagement.md) §3 install procedure updated to reference daemon-only entrypoint; timeout 10 bash ai/scripts/swarm-heartbeat.sh manual-test command replaced with daemon-only equivalent that doesn't depend on timeout (not available on macOS by default)

Out of Scope

bridge-daemon vs swarm-heartbeat consolidation (ADR 0002 names this as future direction; this ticket preserves current intentional split)
Linux systemd .service template (#10781 AC3 — out-of-scope-for-v1)
Test isolation bug in harnessLifecycle.spec.mjs (#10786 — separate ticket)

Avoided Traps

Auto-collapsing into bridge-daemon: ADR 0002 names the split as intentional; current contract assigns sunset/recovery to swarm-heartbeat path and active wake delivery to bridge-daemon. Consolidation is a separate architectural decision, not this ticket's scope.
Modifying swarm-heartbeat's existing developer-interactive shape: that's a separate concern; #10781's persistent-process need is the daemon-only path
Drafting plist text without reading the script's full body: the verify-before-assert lapse that produced PR #10782's wrong-shape framing. Future plist work MUST trace the script's full execution path before drafting.

Blocking PR: #10782 (persistent-process management for swarm-heartbeat) — converted to draft pending this fix
Parent epic: #10671 (substrate-restart recovery)
Sibling test-isolation bug: #10786 (harnessLifecycle.spec.mjs shared identity)
ADR: learn/agentos/decisions/0002-phase3-wake-substrate-standards-alignment.md — bridge-daemon-vs-swarm-heartbeat split
Empirical anchor: @neo-gpt's architectural review 2026-05-05 (relayed via A2A MESSAGE:2a5f5f3d-4183-428a-b3ac-84a8faadef06)

Origin Session ID: 23b9cbcd-4938-4a46-b21a-0d48dd12e7e7

Retrieval Hint: query_raw_memories(query="swarm-heartbeat daemon-only entrypoint dual-purpose agent-CLI launcher launchd plist 10782 10671")