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	11066
title	bridge-daemon launchd/systemd packaging (close operator's bridge terminal)
state	Closed
labels	enhancementaiarchitecturemodel-experience
assignees	[]
createdAt	May 10, 2026, 12:00 AM
updatedAt	May 10, 2026, 12:16 AM
githubUrl	https://github.com/neomjs/neo/issues/11066
author	neo-opus-4-7
commentsCount	1
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	May 10, 2026, 12:16 AM

bridge-daemon launchd/systemd packaging (close operator's bridge terminal)

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

Closedenhancementaiarchitecturemodel-experience

neo-opus-4-7 commented on May 10, 2026, 12:00 AM

Context

Sibling-fileable from PR #11058 (SwarmHeartbeatService class+wrapper split → launchd/systemd-packaged daemon). Operator surfaced 2026-05-09: end-state goal is closing the manually-kept-open bridge terminal + chroma terminal + running orchestrator instead. Bridge terminal is the easiest win.

Empirical state (2026-05-09):

node ai/scripts/bridge-daemon.mjs running PID 63662, started Fri 10PM (12 days uptime)
.neo-ai-data/wake-daemon/bridge.log.YYYY-MM-DD rotation series back to 2026-04-27 — operator has been keeping it alive in a terminal continuously
No npm script ai:bridge exists in package.json (verified via grep)
No launchd plist template exists for bridge-daemon (only com.neomjs.swarm-heartbeat.plist.template is sibling-precedent)
Bridge daemon ALREADY has the right shape internally — it's a long-running process with proper PID-lock per #10422/#10423; just needs persistent-process packaging

Duplicate sweep before filing:

gh issue list --search "bridge-daemon launchd in:title,body" — no matches
gh issue list --search "bridge daemon plist systemd" — no matches
learn/agentos/wake-substrate/PersistentProcessManagement.md documents SwarmHeartbeatService packaging only

The Problem

Operator must keep a terminal open continuously to run node ai/scripts/bridge-daemon.mjs. This is:

Friction — operator can't close the laptop / restart / move to a different machine without losing the bridge daemon
Inconsistent with sibling pattern — SwarmHeartbeatService got launchd/systemd packaging via #11058; bridge is identical-shape persistent-process daemon and deserves the same packaging
Blocks operator's terminal-consolidation goal — three terminals currently (bridge, chroma, optional orchestrator); reducing to zero-terminals is the end-state

The Architectural Reality

Sibling precedent: PR #11058 split SwarmHeartbeatService into:

ai/daemons/SwarmHeartbeatService.mjs (class only)
ai/scripts/swarm-heartbeat-daemon.mjs (entry-point wrapper)
learn/agentos/wake-substrate/com.neomjs.swarm-heartbeat.plist.template
Documentation in learn/agentos/wake-substrate/PersistentProcessManagement.md

Bridge-daemon doesn't need the class+wrapper split (it's already a single entry-point script, not a class). It just needs:

npm script for clean invocation
launchd plist template matching com.neomjs.swarm-heartbeat.plist.template shape
PersistentProcessManagement.md updated to document bridge-daemon packaging in parallel

The Fix

Step 1: Add `ai:bridge` npm script

  "ai:orchestrator"              : "node ./ai/scripts/orchestrator-daemon.mjs",
+ "ai:bridge"                    : "node ./ai/scripts/bridge-daemon.mjs",

Step 2: Create `learn/agentos/wake-substrate/com.neomjs.bridge-daemon.plist.template`

Lift com.neomjs.swarm-heartbeat.plist.template shape:

Label: com.neomjs.bridge-daemon
ProgramArguments: [/usr/bin/env, node, [OPERATOR_REPO_ROOT]/ai/scripts/bridge-daemon.mjs]
WorkingDirectory: [OPERATOR_REPO_ROOT]
KeepAlive: true (long-running daemon)
ThrottleInterval: 10
StandardOutPath/StandardErrorPath: [REPO_ROOT]/.neo-ai-data/wake-daemon/bridge.{stdout,stderr}.log
EnvironmentVariables: PATH + NEO_AI_DAEMON_DIR (optional; defaults to .neo-ai-data/wake-daemon)

Step 3: Update `learn/agentos/wake-substrate/PersistentProcessManagement.md`

Add parallel "Bridge Daemon Installation" section with:

Empirical-prerequisites (verify node, check .neo-ai-data/wake-daemon/ exists, manual one-shot test)
macOS launchd installation (sed substitution + launchctl bootstrap)
Linux systemd .service template (mirroring SwarmHeartbeatService)
Troubleshooting table (similar gotchas: PATH, KeepAlive thrashing, plist sync issues)
Cross-coexistence note: bridge + swarm-heartbeat + orchestrator are independent daemons; can install/uninstall each separately

Step 4: Verify operator-runnable smoke-test

npm run ai:bridge should produce identical behavior to current manual node ai/scripts/bridge-daemon.mjs — no logic changes, only invocation path.

Acceptance Criteria

AC1 — package.json adds ai:bridge npm script invoking node ./ai/scripts/bridge-daemon.mjs
AC2 — learn/agentos/wake-substrate/com.neomjs.bridge-daemon.plist.template exists; mirrors com.neomjs.swarm-heartbeat.plist.template shape
AC3 — learn/agentos/wake-substrate/PersistentProcessManagement.md adds "Bridge Daemon Installation" section with launchd + systemd procedures + troubleshooting + coexistence notes
AC4 — Smoke-test verification: npm run ai:bridge produces identical bridge-daemon behavior to manual node ai/scripts/bridge-daemon.mjs invocation (no logic change)
AC5 — No code changes to ai/scripts/bridge-daemon.mjs itself (the daemon code is already correct-shape; this PR is packaging only)
AC6 — Cross-family review per pull-request §6.1

Out of Scope

Bridge-daemon code refactoring — no class+wrapper split needed (single-file entry-point shape is correct for this daemon's role; #11058 split was specific to SwarmHeartbeatService's hybrid class+self-invoke pattern)
Chroma terminal close — separate sibling work (chroma is a third-party process, not a Neo daemon; needs its own launchd packaging investigation)
Orchestrator daemon launchd packaging — separate sibling; orchestrator boot has its own first-run validation needs (.neo-ai-data/orchestrator-daemon/ directory creation, MC quietness check, etc.)
Auto-installer / installer-script — operator can run the substitution + bootstrap manually per the existing PersistentProcessManagement.md pattern

Avoided Traps

❌ Bundling chroma + orchestrator launchd into this PR — three different daemons, three different first-run validation needs. One ticket = one PR per ticket-create §3.
❌ Refactoring bridge-daemon.mjs internals — it works (PID 63662 has 12-day uptime). Don't fix what isn't broken; just package it.
❌ Hardcoded PATH — must list operator-environment-specific dirs (Homebrew, nvm, etc.) per the SwarmHeartbeatService plist's gotcha note.

Provenance

Operator end-state goal (2026-05-09): "the real goal would be that i close my bridge terminal, and the chroma terminal process, and run the new orchestrator instead"
Empirical anchor (2026-05-09): PID 63662 bridge-daemon Fri 10PM uptime; .neo-ai-data/wake-daemon/bridge.log.YYYY-MM-DD rotation series back to 2026-04-27
Sibling precedent: PR #11058 (SwarmHeartbeatService class+wrapper split with launchd template)
Bridge daemon source: ai/scripts/bridge-daemon.mjs (#10319 / #10422 / #10423 PID-lock substrate)

PR #11058 (sibling: SwarmHeartbeatService launchd packaging — direct precedent shape)
#10422, #10423 (bridge-daemon PID-lock singleton enforcement)
learn/agentos/wake-substrate/PersistentProcessManagement.md (the canonical operator-facing substrate to extend)

Self-Identification: @neo-opus-4-7 (Claude Opus 4.7, Claude Code) — claiming this lane immediately. Non-LLM/non-DB-load work; concrete operator-terminal-close win; sibling-pattern lift from #11058.

Origin Session ID: c2912891-b459-4a03-b2af-154d5e264df1