What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

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

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	13493
title	Mode-aware boot identity healthcheck for memory-core MCP
state	Closed
labels	enhancementaiarchitecturemodel-experience
assignees	neo-opus-ada
createdAt	Jun 19, 2026, 1:55 AM
updatedAt	Jun 19, 2026, 6:34 AM
githubUrl	https://github.com/neomjs/neo/issues/13493
author	neo-opus-ada
commentsCount	1
parentIssue	13012
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 19, 2026, 6:34 AM

Mode-aware boot identity healthcheck for memory-core MCP

Closed v13.1.0/archive-v13-1-0-chunk-4 enhancementaiarchitecturemodel-experience

neo-opus-ada commented on Jun 19, 2026, 1:55 AM

Context

Split from #13488 (item b). #13488 delivers item (a) — the named unboundIdentityError self-diagnosis at the ~17 identity-gated throw sites. This ticket tracks item (b): surfacing the bound/unbound identity status proactively (at boot / via healthcheck) so an identity regression fails-fast or is queryable, instead of surfacing lazily at the first identity-gated tool call.

Carries the cloud-safety guardrail from @neo-opus-grace's cross-family design review of #13488.

Release classification: boardless (agent-os stability/self-healing — not v13 release-blocking). Dup sweep: covered by the #13488 sweep (latest 25 open, 2026-06-19); this is a documented split, no equivalent exists.

The Problem

Server.logIdentityStatus() (ai/mcp/server/memory-core/Server.mjs:441-450) already computes the bound/unbound status at boot and logs it — but only to the server log, invisible to the agent, and not surfaced via the healthcheck tool. So a stale/regressed identity stays silently unbound until the first A2A call fails.

The Architectural Reality

Server.logIdentityStatus() (L441-450) already builds Identity: <userId> via <source> — bound to X / unbound (no matching AgentIdentity node).
Server.bindAgentIdentity() (L404-435) — the lookup; L429 logs the named miss.
aiConfig.auth.mode (ai/config.mjs:108, 'oidc' | 'gitlab-pat', via the AiConfig SSOT per ADR 0019) + AuthService.setup():67 branch — distinguishes single-identity-at-boot (stdio) from per-request identity (SSE multi-user).

The Fix

Surface the identity-resolution status (userId, source, bound/unbound) as a field in the healthcheck tool output — queryable, not log-only.
Mode-aware fail-loud (CRITICAL — cloud guardrail): flag/fail-fast the unbound-at-boot case ONLY under the local stdio single-identity path (this.stdioIdentity with source:'env-var' and a null agentIdentityNodeId — the regression). Under gitlab-pat/multi-user mode, identity is per-request from the bearer (no single boot identity) → the check MUST be a no-op there; a naive boot-fatal check would fail-fast-kill the multi-user MC boot. Preserve the existing source:'unresolved' single-tenant non-fatal fallthrough.

Cloud-impact AC (from @neo-opus-grace)

Boot/healthcheck identity enforcement is gated on local single-identity mode; under per-request (gitlab-pat) multi-user mode it is a verified no-op — confirmed not to abort multi-user MC boot. PR must carry an explicit cloud-impact line.

Decision Record impact

none — observability over the existing identity-resolution design; aligned with #10692 (RequestContextService) + #11318.

Acceptance Criteria

healthcheck output includes resolved identity status (userId / source / bound|unbound).
Boot-time fail-loud (or surfaced warning) for the stdio env-var present-but-unresolvable case.
Mode-aware: enforcement is a no-op under gitlab-pat/per-request multi-user mode (verified not to abort boot).
Unit coverage: stdio env-var unbound (flag), gitlab-pat multi-user (no-op), unresolved single-tenant (non-fatal).

Out of Scope

The named throw-site errors (item a — delivered in #13488 via RequestContextService.unboundIdentityError).
Harness config-recovery / stale-snapshot fragility (separate harness/operator note).

Split from #13488 (item a delivered there); parent epic #13012. Builds on the unboundIdentityError helper from #13488.

Handoff Retrieval Hints

Retrieval Hint: logIdentityStatus healthcheck mode-aware gitlab-pat no-op boot identity

Origin Session ID: 0f7b7d69-7c6c-4699-b17f-09044426f2e3