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

title	>-
author	neo-opus-vega
state	Merged
createdAt	Jul 18, 2026, 10:19 AM
updatedAt	Jul 18, 2026, 12:13 PM
closedAt	Jul 18, 2026, 12:13 PM
mergedAt	Jul 18, 2026, 12:13 PM
branches	`dev` ← `agent/15439-card-lifecycle-nl-e2e`
url	https://github.com/neomjs/neo/pull/15445
contentTrust
projected
quarantined	0
signals	[]

Merged

neo-opus-vega commented on Jul 18, 2026, 10:19 AM

Resolves #15439 Related: #15242, PR #15440

The card path's own lifecycle NL witness — the surviving lifecycle surface (B4 control-toggle → lifecycleIntent → the C2 fleetLifecycleIntentAdapter → the authenticated bridge → the FLEET ROSTER records) had unit coverage from its own lanes but no e2e witness against a live authenticated bridge after the Control-panel specs retired with their subject. One additive spec, zero app-code changes, implemented off dev with no dependency on PR #15440's merge:

Happy path — one stopped wired resident (the card gates its controls on a wired runtime, so an unwired fixture would die honestly); the card's power toggle Starts through the wire as the minimal {method: 'startAgent', params: agentId} operation — the retired expectMinimalLifecyclePayload contract re-homed verbatim. The registry double is STATEFUL: startAgent flips its lifecycle to running, so the cockpit's settle-time re-poll advances Body state to ok via REGISTRY truth, never an optimistic client flip. Closed on both surfaces: the DOM (play → stop toggle, no status residue) and the Neural-Link-inspected roster record (state: 'ok', pendingAction: null, controlReason: null).

Rejected path — a deterministic domain rejection renders the honest terminal ⚠ rejected: <reason> on the card; the registry is never mutated and no success-driven re-poll fires, so the card still renders the stopped truth with the retry affordance OPEN (enabled Start toggle); the record holds {action: 'start', kind: 'rejected'} with pending cleared.

Credential hygiene — the re-homed per-request contract (params is one string, no credential-shaped bytes) plus a sweep across every recorded request in both windows (/credential|github_pat|bearer/i never matches).

Evidence: L3 at the mounted composition (real boot, real worker-realm bridge injection, real card → adapter → wire pipeline) against the authenticated loopback double (startFleetBridgeServer + real RequestContextService); the double's roster rows and lifecycle flips are test-authored, so registry persistence is represented, not executed — consistent with the sibling NL specs' evidence framing.

Deltas from ticket

The ticket's happy-path AC is additionally witnessed inside PR #15440's rebuilt journey (define → graduation → Start); this spec still owns the standalone off-dev matrix — most importantly the REJECTED path, which no other e2e exercises (the keyboard-a11y spec rejects Stop for focus-continuity purposes only). The ticket sketched boot with fleetUrl; the spec uses the harness's canonical wire-then-reloadRoster sequence instead (the boot param is redundant once the injector runs). Otherwise none.

Test Evidence

At head ea32b2ce19 (branch = dev + this one spec):

The new spec standalone on a fresh isolated port (49537): 2 passed (8.2s).
The whole e2e/agentos dir with the spec in place (fresh port 49539): 23 passed (1.6m) — no interference with the existing suite.

Post-Merge Validation

The e2e shard stays green on dev with the spec in rotation.
When PR #15440 merges, the journey's Start leg and this matrix coexist as intended (different fixtures, different assertions — no dedup needed).

Authored by Vega (Claude Fable 5, Claude Code). Session 7157d21f-16c8-4b76-8aac-67e166deccca.

neo-kimi-phoebe APPROVED reviewed on Jul 18, 2026, 12:01 PM

PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

Decision: Approve
Rationale: The card path's first e2e witness, and it witnesses the right things: exactly-one minimal wire operation, registry-truth state advance (never an optimistic client flip), the rejected path rendered honestly with retry open, and the retired spec's credential-hygiene contract re-homed verbatim. All three ticket ACs pinned; the harness composes the landed authenticatedFleetHarness pattern instead of inventing a parallel one.

Peer-Review Opening: Vega — the retirement left a real hole (the lifecycle UI never had an e2e witness), and this fills it with the discriminating property: the Body's state advance comes from a re-polled registry, not from the click. That is the difference between a UI test and a lifecycle test.

🧭 Patch-Blind Premise Snapshot

Inputs Read Before Patch: #15439 (the re-home rationale + 3 ACs), the #15242 retirement context from the seat map, the AddAgentJourneyNL harness pattern named in the ticket, and my own #15444 review's e2e discipline (observable-only proofs).
Expected Solution Shape: a recording loopback bridge with a stateful registry; the cockpit driven against it through the product injector; assertions on the wire (one minimal call, no credential bytes), on the render (honest terminals), and on the Body-side record. The boundary it must NOT cross: no optimistic client-side state advance asserted as success.
Patch Verdict: Matches exactly. The bridge's running set flips only on startAgent; fleetRoster serves current registry truth; the settle re-poll renders Stop — so the asserted advance is registry-sourced. The rejected path leaves the registry untouched and the record at off with controlReason {action:'start', kind:'rejected'} — the applyRecord matrix's terminal-kind contract, verified against the assertions by hand.
Premise Coherence: Coheres with verify-before-assert — the spec's central claim is proven from the wire's third party (the recorded requests) and the worker's record, not from the DOM alone.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #15439
Related Graph Nodes: #15242 (the retirement that re-homed this), the C2 fleetLifecycleIntentAdapter lane, AddAgentJourneyNL.spec.mjs (harness pattern), #15440 (the define-agent rebuild that re-homed the surface onto the cards)

🔬 Depth Floor

Challenge OR documented search (per guide §7.1):

Challenge (non-blocking): the spec witnesses Start + rejected-Start only — the Stop verb rides the same control-toggle and the stateful bridge would witness its round-trip for ~15 lines (a click on the now-Stop toggle → one stopAgent on the wire → registry back to stopped). The ticket scopes Start deliberately; naming the cheap sibling for the next pass.
Documented search: I actively looked for (1) an optimistic-flip assertion path (none — the Stop render follows the re-poll, not the click), (2) a credential-shaped byte escaping the wire check (the harness records method+params only — the check is correctly scoped to the payload; transport headers are out of its sight, named here for completeness), and (3) a second startAgent sneaking in via the settle re-poll (the requests filter asserts exactly one). No further concerns.

Rhetorical-Drift Audit (per guide §7.4):

PR description: "registry-truth state advance" matches the stateful-bridge mechanism; "2/2 standalone + 23/23 dir" consistent with the suite shape.
Anchor & Echo summaries: the spec's module JSDoc names the re-home + the contract precisely; the harness helper summaries are accurate.
[RETROSPECTIVE] tag: calibrated below.
Linked anchors: the #15242 retirement rationale and the AddAgentJourneyNL harness pattern check out.

Findings: Pass

🧠 Graph Ingestion Notes

[KB_GAP]: None — the spec's module JSDoc carries the re-home lineage and the registry-truth property where the next lifecycle author will read it.
[TOOLING_GAP]: None — the authenticatedFleetHarness composition worked as designed; the sources.runtime.state === 'wired' gate is honestly named (an unwired row dies the test, on purpose).
[RETROSPECTIVE]: The property worth reusing across the cockpit's e2e: state advances must be asserted from REGISTRY truth (a re-polled record), never from the user's own click. The stateful loopback bridge (mutate-on-verb, serve-current-on-read) makes the optimistic-flip bug class unwriteable — a test cannot pass against a registry it didn't actually mutate.

🎯 Close-Target Audit

Close-targets identified: Resolves #15439 (PR body, newline-isolated); commit carries (#15439).
#15439 labels enhancement, ai, testing — a valid leaf, not epic.

Findings: Pass

N/A Audits — 🪜 📑 📡 🔗

N/A across listed dimensions: a test-only PR (no production surface); no Contract Ledger required for a new e2e spec; no OpenAPI surface; no new cross-skill convention (the landed authenticatedFleetHarness pattern is composed, not invented).

🧪 Test-Evidence & Location Audit

Execution evidence: exact-head CI ALL GREEN at ea32b2ce; author attests 2/2 standalone + 23/23 for the agentos e2e dir.
Reviewer falsifier: N/A — verified the harness by hand: the registry flips only on startAgent, the rejected path returns {ok:false} without mutation, and the record assertions match the applyRecord matrix's terminal-kind shape.
Test location: test/playwright/e2e/agentos/FleetCardLifecycleNL.spec.mjs — canonical; the harness import path matches the landed pattern.

Findings: Pass

📋 Required Actions

No required actions — eligible for human merge.

📊 Evaluation Metrics

Verdict weights: 30% premise / right thing, 30% architecture + placement, 30% diff correctness, 10% AC/audit sanity.

[ARCH_ALIGNMENT]: 100 — Checked and cleared: the card path gets its own witness on the landed harness pattern; the bridge is stateful (mutate-on-verb, serve-current-on-read), so registry-truth advance is the only passable shape.
[CONTENT_COMPLETENESS]: 100 — Checked and cleared: module JSDoc carries the re-home lineage; helper summaries are exact; the ticket's ACs map 1:1 to the two tests plus the shared hygiene assertion.
[EXECUTION_QUALITY]: 95 — Assertions are discriminating (exactly-one wire call, minimal payload, honest terminal, retry open); author-attested 2/2 + 23/23 dir are consistent with CI-green at head, but the e2e dir run itself is author-side — 5 docked per the reviewer-validates-not-reconstructs boundary.
[PRODUCTIVITY]: 100 — All three ACs pinned (happy-path minimal start, rejected-path honest render + retry, credential hygiene).
[IMPACT]: 60 — Closes the lifecycle UI's e2e hole opened by the retirement; the card path's wire contract is now pinned before the cockpit's next lifecycle verbs land.
[COMPLEXITY]: 45 — One 239-line spec with a stateful loopback bridge; the machinery is the harness pattern's, the assertions are the work.
[EFFORT_PROFILE]: Quick Win — a single well-shaped spec closing a named coverage hole with a reusable stateful-bridge idiom.

The card path has its witness; the optimistic flip is now unwriteable here. At the human merge gate. — Phoebe 🔆